Installation and First Launch - Troubleshooting

This troubleshooting guide covers the most common problems during Claude Code installation and first launch: Node.js errors, version conflicts, authentication failures, and startup freezes. You will find ready-to-use diagnostic commands and tested solutions for each situation.

Troubleshooting the installation and first launch of Claude Code is a step that the majority of new users encounter at least once. Claude Code runs on a compatible operating system (macOS, Linux, Windows native or via WSL2) and the recommended native installer needs no Node.js at all. Node.js 18 or higher is required only if you install through the npm method. This guide walks you through identifying and resolving each blocker step by step.

How to install Claude Code without errors?

The recommended installation method is the native installer, a self-contained binary that auto-updates and does not require Node.js. Choose the command for your platform:

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

:: Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Several first-class alternatives are available as well:

The npm method is a secondary alternative and is the only path that requires Node.js. If you choose it, install Node.js 18 or higher first. Node.js is not a prerequisite for Claude Code in general, only for this specific install path.

Run these commands to check your operating system and available disk space:

uname -a
df -h

If you are using the npm method and your Node.js version is below 18, check the installation and first launch tutorial which details the update procedure. In practice, switching to the native installer removes the vast majority of Node.js-related prerequisite errors entirely.

Key takeaway: prefer the native installer; Node.js 18+ is required only for the npm method.

How to diagnose Claude Code installation errors?

When installation fails, your first reflex should be to read the complete error message. If you installed through npm, run the installation in verbose mode to get detailed logs:

npm install -g @anthropic-ai/claude-code --loglevel verbose

Verbose mode displays each download and compilation step, which helps identify the blocking point.

If you encounter an EACCES error during an npm install, it is a permissions problem. Configure npm to use a local directory:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH="$HOME/.npm-global/bin:$PATH"

Add the export PATH line to your ~/.bashrc or ~/.zshrc file to make it permanent. To understand the permissions and security mechanisms in Claude Code, check the dedicated guide on common errors.

In practice, the EACCES error accounts for a notable share of installation-related support tickets on Linux and macOS.

Key takeaway: --loglevel verbose mode is your best diagnostic tool during installation.

What are the 12 most common problems on first launch?

Here is the reference table of symptoms, causes, and solutions. This table covers cases reported by the community between 2024 and February 2026.

This table resolves the majority of reported problems. For cases not covered, the general Claude Code troubleshooting page provides additional solutions.

Key takeaway: check this table first. It covers the vast majority of installation and launch blockers.

How to resolve PATH and command not found issues?

The command not found: claude error is the number one problem after installation. It means your shell does not know where to find the Claude Code executable.

Run this command to locate the installation:

npm list -g --depth=0 | grep claude
npm config get prefix

the binary installs in the bin folder of the npm global prefix. On macOS with Homebrew, this path is often /usr/local/bin. On Linux, it may be /usr/lib/node_modules/.bin.

Here is how to fix it depending on your shell:

After modification, reload your configuration:

source ~/.zshrc # or ~/.bashrc depending on your shell
which claude

The which claude command should return a valid path. If you use nvm, the path changes with each Node.js version switch. The installation and first launch guide details managing nvm with Claude Code.

Key takeaway: after each installation, verify the PATH with which claude before reporting a problem.

How to fix authentication and API key errors?

Authentication is the second source of blockers after installation. The primary method is interactive login: run claude and complete the browser OAuth flow (or use /login within a session) with a Pro, Max, Team, Enterprise, or Console account. The ANTHROPIC_API_KEY path is for API and Console billing users, and Claude Code also supports Amazon Bedrock and Google Vertex AI.

Run the interactive login:

claude
# then complete the browser OAuth flow, or run /login in an existing session

If you authenticate through the API, a significant share of authentication errors come from a misconfigured ANTHROPIC_API_KEY environment variable. Check its presence:

echo $ANTHROPIC_API_KEY

If the variable is empty or incorrect, configure it:

export ANTHROPIC_API_KEY="sk-ant-your-key-here"

If you encounter persistent errors during your first conversations with Claude Code, the issue often comes from a reached API quota. Limits depend on your subscription plan (Pro, Max, Team, or Enterprise).

Key takeaway: always run claude to trigger the browser login (or /login in session) before looking for other causes of malfunction.

Why does Claude Code freeze or become unresponsive at startup?

A startup freeze generally indicates a process conflict or a lock file issue. Claude Code creates a temporary file in ~/.claude/ during launch.

Check if a Claude process is already running:

ps aux | grep -i claude
lsof -i :3000-3100

If an orphan process exists, terminate it properly before relaunching:

pkill -f "claude"
rm -f ~/.claude/*.lock
claude

In practice, this scenario occurs in most cases when the previous terminal was closed abruptly. The .lock file prevents two Claude Code instances from running simultaneously.

On WSL2 (Windows Subsystem for Linux), an additional issue can arise: the Windows-Linux interop slows file access. In practice, startup on WSL2 can be noticeably slower than on native Linux due to the Windows-Linux filesystem interop.

For issues related to memory configuration, the guide on the CLAUDE.md memory system explains how a corrupted CLAUDE.md file can block startup.

Key takeaway: delete .lock files in ~/.claude/ if Claude Code remains frozen on launch.

How to resolve proxy and network issues in enterprise environments?

Enterprise environments add a layer of complexity with proxies, firewalls, and custom SSL certificates. Claude Code requires outbound HTTPS access to api.anthropic.com on port 443.

Test network connectivity:

curl -v https://api.anthropic.com/v1/messages 2>&1 | head -20
nslookup api.anthropic.com

If the test fails, configure the proxy for npm and Claude Code:

npm config set proxy http://your-proxy:8080
npm config set https-proxy http://your-proxy:8080
export HTTPS_PROXY=http://your-proxy:8080

For enterprise self-signed certificates, add the CA certificate:

export NODE_EXTRA_CA_CERTS="/path/to/enterprise-certificate.pem"

The Anthropic API usually responds quickly. If your latency climbs to several seconds, the proxy is likely the cause. If MCP servers fail to connect through the proxy, you can adjust the startup timeout with the configurable MCP_TIMEOUT environment variable.

This proxy configuration is identical to the one used for Git integration with Claude Code, since both tools share the same network environment variables.

Key takeaway: export HTTPS_PROXY and NODE_EXTRA_CA_CERTS in your shell profile for enterprise environments.

What diagnostic commands to run before contacting support?

Before opening a ticket, gather complete system information. Here is the diagnostic script to run in a single block:

echo "=== Claude Code Diagnostic ==="
echo "Date: $(date)"
echo "OS: $(uname -a)"
echo "Node: $(node --version)"
echo "npm: $(npm --version)"
echo "Claude: $(claude --version 2>/dev/null || echo 'not installed')"
echo "npm PATH: $(npm config get prefix)"
echo "Proxy: $(npm config get proxy)"
echo "API Key: $(echo $ANTHROPIC_API_KEY | cut -c1-10)..."
echo "Disk space: $(df -h . | tail -1)"
echo "Free RAM: $(free -h 2>/dev/null || vm_stat 2>/dev/null | head -5)"

This script generates a 15 to 20-line report containing all information needed by technical support. Copy the complete output into your ticket.

In practice, a ticket that includes this diagnostic output is typically resolved faster than one without system information.

For issues related to essential slash commands, add the output of claude --help to your report.

The available support channels are: the GitHub repository anthropics/claude-code for public issues, and the community forum for general questions.

Key takeaway: run the complete diagnostic script and attach its output to any support request.

Should you reinstall Claude Code or can you repair the existing installation?

in most cases, a repair is sufficient. A complete reinstallation is only necessary if binary files are corrupted. Here is the decision tree:

Check installation integrity with:

npm doctor
npm ls -g @anthropic-ai/claude-code

The npm doctor command runs several environment checks (registry connectivity, permissions, cache, and installed versions) and reports any problems it finds. If any check fails, the output tells you which correction to apply.

For a clean update, the installation and first launch checklist provides the validated step-by-step procedure. SFEIR Institute recommends this checklist for every major Claude Code update.

To master these maintenance operations and many more, the Claude Code training from SFEIR offers a full day of hands-on labs covering installation, advanced configuration, and troubleshooting. If you want to go further, the 2-day AI-Augmented Developer training integrates Claude Code into a complete development workflow, with exercises on Git integration, automated testing, and AI pair-programming.

Key takeaway: prefer npm rebuild and npm doctor before considering a full reinstallation.

How to avoid recurring problems with MCP extensions?

The Model Context Protocol (MCP) is Claude Code's extension system. MCP lets you connect Claude Code to external tools like databases, APIs, or remote file systems. A misconfigured MCP causes a small share of post-installation problems.

Check your configured MCP servers:

claude mcp list

The most frequent MCP errors come from servers that are not responding or incompatible versions. The MCP: Model Context Protocol troubleshooting guide covers each case in detail.

MCP is built on JSON-RPC 2.0 and supports several transports (stdio, HTTP, and SSE). Choose the transport that fits your server, keeping in mind that HTTP is the recommended option for remote servers.

For developers who want to go deeper into advanced MCP configurations, the AI-Augmented Developer - Advanced training from SFEIR offers an intensive one-day session with labs on agent orchestration and custom MCP extensions.

Key takeaway: list your MCP servers with claude mcp list as soon as unexpected behavior occurs after installation.

When should you contact Anthropic technical support?

Contact support if your problem persists after following all the steps in this guide. Here are the criteria for deciding:

Open a GitHub ticket if: the error is reproducible, the diagnostic script reveals no anomaly, and the problem occurs on a clean installation. Reproducible bugs reported with a clean diagnostic are more likely to be triaged and fixed quickly.

Check the community forum if: the problem is intermittent or related to a specific configuration. An active community forum gathers users who often share the same issues and their solutions.

Check the Anthropic status page first: API incidents account for a small share of problems reported as installation bugs. Unusually high API latency may indicate a server-side incident; check the Anthropic status page.