Claude Code Process Exited With Code 1: How to Fix It

Claude Code process exited with code 1 means the CLI crashed under VS Code or the Agent SDK. How to find the real error and fix login, PATH and MCP causes.

Josh Pocock8 min read

Exit code 1 cover

AI Coding

Exit code 1

Stride AI Academy

"Claude Code process exited with code 1" means the claude process that a launcher started for you, such as the VS Code extension, the Claude Desktop app or an Agent SDK application, stopped with an error. The message comes from the launcher, not from Claude Code. Anthropic's docs say the exit code alone doesn't tell you what failed: the real error is in the process's own output, so the fix starts with finding that output.

This guide covers where the error comes from, how to see the underlying message and the documented fixes for the causes behind it. Everything here was checked against Anthropic's error reference, the Agent SDK troubleshooting docs, the installation and login troubleshooting docs, the VS Code docs, Debug your configuration and the permission modes docs on November 21, 2026.

Where this error comes from

Claude Code is a command line program. The VS Code extension, the Desktop app and the Agent SDK all start it in the background and talk to it. When that background process exits with a nonzero code, the launcher reports it:

Error: Claude Code process exited with code 1

The error reference files it under "Wrapper and IDE errors", meaning messages the launching program prints rather than Claude Code itself. Code 1 is a generic failure. It could be a login problem, a missing binary, a broken config or a crash. That's why searching for the message alone rarely gives you one answer.

Step 1: get the real error message

Do this before you change anything. The docs list four ways to see what actually failed:

  1. In VS Code, click the View output logs link shown with the error. You can also run Claude Code: Show Logs from the Command Palette.
  2. Run claude in a terminal in the same project. The docs say the failure usually reproduces there with its real error message.
  3. Run claude doctor in a terminal to check the installation and configuration. Inside a working session, /doctor does the same.
  4. In an Agent SDK app, capture stderr (see below).

For more detail from the CLI, turn on debug logging. You can filter it by category or write it to a file:

Terminal
claude --debug
claude --debug='mcp,startup'
claude --debug-file /tmp/claude-debug.log

Once you have the real message, look it up in the error reference. The sections below cover the causes the docs connect to this error.

Capture stderr in an Agent SDK app

The SDKs report this exit differently, and the default message hides the useful part.

TypeScript. A nonzero exit rejects the for await loop over query() with a plain Error. There's no special error class, so wrap the loop in try/catch and match on the message. When the CLI wrote to stderr, the message ends with its tail:

Claude Code process exited with code 1. stderr: <tail of the CLI's stderr>

Python. The SDK raises a ProcessError:

Command failed with exit code 1 (exit code: 1)
Error output: Check stderr output for details

That Error output line is fixed text, not your error. In both SDKs, pass a stderr callback in the options and log what it receives to see what the CLI actually wrote.

If the CLI reported an error before exiting, both SDKs show Claude Code returned an error result: followed by the CLI's own report instead. Start with that text.

Fix 1: login and API key problems

If the real error says Not logged in · Please run /login, no valid credential reached the process. The docs' fixes:

  • Run /login in a terminal session to sign in with your Claude subscription or Console account
  • If you rely on an environment variable, confirm ANTHROPIC_API_KEY is set and exported in the shell that launches claude
  • For automation with no interactive login, use an apiKeyHelper script
  • Run /status to see which credential Claude Code is using

If it says Invalid API key · Fix external API key, check the key in the Console and look for a stale one loaded from a .env file:

Terminal
env | grep ANTHROPIC

In PowerShell, use Get-ChildItem Env:ANTHROPIC*. To fall back to subscription login, unset ANTHROPIC_API_KEY and run /login.

VS Code has a specific trap here. If your key is set in your shell but the extension still asks you to sign in, VS Code may not have inherited your shell environment. The docs suggest launching it from a terminal with code ., or signing in with your Claude account instead.

When login keeps failing for no clear reason, the documented reset is /logout, close Claude Code, then run claude and sign in again.

Fix 2: the CLI isn't installed, can't be found or won't launch

A launcher can only start a claude it can find and run.

Check it runs on its own:

Terminal
claude --version

If that says command not found, the install folder isn't on your PATH. The native installer puts claude in ~/.local/bin/claude on macOS and Linux, or %USERPROFILE%\.local\bin\claude.exe on Windows. Our install guide covers setup from scratch.

Check for duplicate installs. The docs warn that several installations can cause version mismatches. On macOS and Linux, which -a claude lists every copy on your PATH.

For SDK apps, the docs list specific messages:

  • CLINotFoundError (Python): confirm claude --version works in the same environment your app runs in. Processes started by an IDE or a service manager often have a different PATH.
  • Native CLI binary for <platform>-<arch> not found (TypeScript): the install skipped optional dependencies. Reinstall @anthropic-ai/claude-agent-sdk without skipping them, or point pathToClaudeCodeExecutable at a native install.
  • Refusing to execute batch script (Python on Windows): the SDK won't run npm's claude.cmd shim. Install natively with irm https://claude.ai/install.ps1 | iex or point cli_path at a claude.exe.
  • A binary that exists but fails to launch: in containers, the usual cause is a binary that doesn't match the container's architecture or libc, or one that lost its execute permission during the image build.

For VS Code on Windows, Could not locate the Claude CLI on PATH means the PATH entry may live only in your PowerShell profile, which the extension doesn't run. Set it as a user or system environment variable and restart VS Code. If the extension says it can't find the Claude Code program for your computer, reinstall it or set claudeCode.claudeProcessWrapper to a separately installed claude binary.

Is Node the problem? Usually not. The npm package needs Node.js 22 or later to install, but the setup docs say the installed binary doesn't use Node at runtime.

Fix 3: MCP servers, hooks and other config

A broken customization can stop Claude Code from starting. The quickest test is safe mode, which skips CLAUDE.md, skills, plugins, hooks, MCP servers and custom output styles while keeping login and built-in tools working:

Terminal
claude --safe-mode

If the problem goes away, one of those is the cause. For MCP servers, run /mcp to see which show as failed. The docs name relative paths in command or args as a frequent cause, because they resolve against the folder you launched from. For more detail, run claude --debug=mcp and read the server's stderr in ~/.claude/debug/<session-id>.txt. Our guide to adding MCP servers covers the config format.

A related message, Subprocess initialization did not complete within 60000ms, means the process didn't report ready in time. The docs point at slow plugins, MCP servers, hooks, disks or network, and say to check how long your SessionStart and Setup hooks run.

Fix 4: bypass mode as root

On Linux and macOS, Claude Code refuses to start in bypassPermissions mode as root or under sudo:

--dangerously-skip-permissions cannot be used with root/sudo privileges for security reasons

This catches SDK apps and scripts in Docker containers that run as root. Run Claude Code as a non-root user, for example with Anthropic's dev container setup. Our guide to skip permissions explains when this mode is safe at all.

Fix 5: Windows exits after a turn

On Windows, the docs say the native build can exit with code 4294967295 right after a turn completes. Since v2.1.273, the VS Code extension closes the session quietly in that case instead of showing the error, and your next message resumes the conversation. If you see it at every turn boundary, update the extension.

What other users have reported

The anthropics/claude-code issue tracker has many reports of this message. These are user reports, not Anthropic's diagnosis, but they show the range of triggers people describe:

  • Every message failing in the Desktop app while the terminal CLI worked (#39270)
  • Crashes on Windows after tool calls with large output (#90168)
  • The VS Code extension failing to open a background session (#77162)
  • Remote SSH sessions from the Desktop app crashing at start (#56840)

If your case isn't covered, file a new issue with the real error from your logs. SDK problems go to the TypeScript SDK or Python SDK repositories, with the full error text and your SDK version.

Learn to build with Claude Code

The Stride AI Coding course teaches Claude Code and Codex for building client tools, written for non-programmers, with weekly live calls to review your builds. Many of the free guides cover Claude Code setups, and the Claude Code community is where members compare theirs.

FAQ

What does "Claude Code process exited with code 1" mean?

It means the background claude process started by VS Code, the Desktop app or an Agent SDK app exited with an error. The launcher prints the message, and the real cause is in the process's own output or logs.

How do I see the real error behind exit code 1?

In VS Code, click View output logs or run Claude Code: Show Logs. Otherwise run claude in a terminal in the same project, where the failure usually shows its real message, and run claude doctor to check your setup.

How do I fix exit code 1 in VS Code?

Open the output logs first. Common documented fixes are signing in again with /login, launching VS Code from a terminal with code . so it inherits your API key, and fixing PATH on Windows so the extension finds the installed CLI.

Why does the Agent SDK say "Check stderr output for details"?

In the Python SDK that line is fixed text, not your error. Pass a stderr callback in the options to log what the CLI actually wrote.

Can an MCP server cause exit code 1?

A broken customization can stop startup, and MCP servers are one documented suspect. Start with claude --safe-mode; if the error goes away, check /mcp and run claude --debug=mcp to read the failing server's output.

Does running as root cause this error?

It can in bypass mode. On Linux and macOS, Claude Code refuses to start with --dangerously-skip-permissions as root or under sudo, so run it as a non-root user.

Build it with us in Stride AI Academy

Four courses, weekly live calls and a community of people building and selling AI. Or start with 320+ free guides.

Keep reading

Free AI Coding guides