Claude Code Installation Failure Due to Stale Lock File

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Bug Report: Claude Code Installation Failure Due to Stale Lock File

Summary

The Claude Code installer fails when a stale lock file exists from a previous installation attempt, providing confusing error messages and ignoring the --force flag suggestion.

Environment

• OS: macOS (Darwin arm64)
• Shell: zsh
• Claude Code Version: 2.0.71
• Installation Method: curl -fsSL https://claude.ai/install.sh | bash -s latest

Steps to Reproduce

1. Attempt to install Claude Code using the official installer:

``bash
curl -fsSL https://claude.ai/install.sh | bash -s latest
``

1. Installation fails or is interrupted (e.g., due to macOS Gatekeeper killing the process)
2. Attempt to reinstall using the same command
3. Observe the error message persists
4. Note: The issue persists even after:

• Closing the Claude desktop app completely
• Restarting the computer multiple times
• Waiting extended periods between attempts

Expected Behavior

The installer should:

1. Detect stale lock files and remove them automatically
2. Provide a clear, actionable error message if manual intervention is needed
3. Respect the --force flag to bypass lock file checks
4. Report accurate installation status (success OR failure, not both)

Actual Behavior

The installer produces confusing output:

Setting up Claude Code...

✘ Installation failed

Could not install - another process is currently installing Claude. Please try 
again in a moment.

Try running with --force to override checks

✅ Installation complete!

Issues observed:

1. Reports both "Installation failed" AND "Installation complete" (contradictory)
2. The --force flag mentioned in the error doesn't work:

``bash
curl -fsSL https://claude.ai/install.sh | bash -s latest --force
# Same error occurs
``

1. The error persists even when no installation process is running
2. The error persists even after closing all Claude apps and restarting the computer
3. The binary is not actually installed to ~/.local/bin/claude

Root Cause

A stale lock file at /Users/MalikRigot/.local/state/claude/locks/2.0.71.lock prevents installation from proceeding. This lock file:

• Persists across system reboots
• Is not automatically cleaned up when the installation process dies
• Has no expiration mechanism
• Cannot be bypassed even with the suggested --force flag

Workaround

Manual removal of the stale lock file:

rm /Users/MalikRigot/.local/state/claude/locks/2.0.71.lock

Then rerun the installer.

Suggested Fixes

Priority 1: Handle Stale Lock Files

The installer should:

• Check if the process ID in the lock file still exists
• If the process is gone, automatically remove the stale lock and continue
• Log when removing a stale lock: "Removed stale lock from previous installation"

Priority 2: Improve Error Messaging

• Don't report both success and failure - this is extremely confusing
• If lock file exists and process is running: "Installation already in progress (PID: XXXX)"
• If lock file exists but process is dead: "Stale lock file detected, removing automatically..."
• Make the error message more specific about the lock file location

Priority 3: Implement --force Flag Properly

The install script suggests using --force but:

• The outer shell script doesn't accept a --force parameter
• The inner claude install command may accept it, but users can't pass it through the curl pipe
• Either:
• Make the shell script accept and pass through --force
• OR remove the suggestion from the error message

Additional Context

Lock File Persistence

The stale lock file is the core issue:

• Location: ~/.local/state/claude/locks/[version].lock
• Persists across system reboots
• Not cleaned up automatically when installation process terminates unexpectedly
• No timeout or expiration mechanism

Lock File Details

Lock file location: ~/.local/state/claude/locks/[version].lock

The installer should implement process liveness checking:

if [ -f "$LOCK_FILE" ]; then
    lock_pid=$(cat "$LOCK_FILE")
    if ! kill -0 "$lock_pid" 2>/dev/null; then
        echo "Removing stale lock file..."
        rm "$LOCK_FILE"
    fi
fi

Impact

• Severity: High - Prevents new users from installing Claude Code
• Frequency: Common - Occurs whenever installation is interrupted or fails
• User Experience: Very poor - Contradictory messages and ineffective troubleshooting suggestions

Reproduction Rate

100% when stale lock file exists from previous installation attempt.

---

Reporter Notes:
This issue was discovered when attempting to install Claude Code. The installation repeatedly failed with the same error message even after:

• Closing all Claude applications
• Restarting the computer multiple times
• Waiting extended periods between installation attempts

The error persisted until manually removing the lock file at ~/.local/state/claude/locks/2.0.71.lock based on the help message from the claude install --help command. The lock file's persistence across reboots and lack of automatic cleanup makes this a critical usability issue for new users.

What Should Happen?

The installer should:

Detect stale lock files and remove them automatically
Provide a clear, actionable error message if manual intervention is needed
Respect the --force flag to bypass lock file checks
Report accurate installation status (success OR failure, not both)

Error Messages/Logs

Steps to Reproduce

Attempt to install Claude Code using the official installer:

bash curl -fsSL https://claude.ai/install.sh | bash -s latest

Installation fails or is interrupted (e.g., due to macOS Gatekeeper killing the process)
Attempt to reinstall using the same command
Observe the error message persists
Note: The issue persists even after:

Closing the Claude desktop app completely
Restarting the computer multiple times
Waiting extended periods between attempts

Claude Model

None

Is this a regression?

Yes, this worked in a previous version

Last Working Version

_No response_

Claude Code Version

2.0.71 (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

_No response_