"Claude Code process exited with code 1" is a catch-all failure message that shows up when the background Claude Code process crashes before it can return a response. The message itself tells you almost nothing. The real cause is usually in the lines above it in the output panel, and it tends to fall into a short list of recurring problems: unaccepted terms on your Anthropic account, a broken authentication state, a bad working directory, a missing system dependency like Git, or a corrupted session.
Quick answer: Sign in to claude.ai in a browser and accept any pending terms or policy updates, then restart Claude Code. If the error still appears, open a terminal, run claude to re-authenticate, and confirm your project path contains no spaces and Git is installed.
What the error actually means
Exit code 1 is a generic non-zero return status from a child process. When the Claude Code CLI, the VS Code extension, or the desktop app spawns the underlying claude binary and that binary terminates with status 1, the host surfaces the message verbatim. It covers authentication failures, unaccepted policies, missing runtime dependencies, corrupted session state, large tool outputs, and environment variable conflicts.
Because the symptom is shared across very different root causes, fixing it is a process of elimination. Start with the most common and cheapest fixes before rebuilding your environment.
Accept pending Anthropic terms
The most frequent cause on the VS Code extension and Cursor integration is a pending terms or policy acceptance on your Anthropic account. The CLI authenticates successfully, but the session refuses to start because the account has an unsigned agreement.
Step 1: Open claude.ai in a browser and sign in with the same account you use in Claude Code.
Step 2: Look for a banner or modal asking you to accept updated terms of service or usage policies. Accept anything pending. If you use multiple accounts (personal, Team, Enterprise), repeat for each.
Step 3: Fully quit and reopen your editor, then start a new Claude Code session. The error should no longer appear on startup.
Re-authenticate from the terminal
If the extension fails to launch a session but the CLI works, the stored credentials for the IDE integration are likely stale or incomplete.
Step 1: Open the integrated terminal in VS Code or Cursor.
Step 2: Run claude. If authentication is needed, you will be prompted to log in through the browser or enter an API key.
Step 3: Complete the flow, close the terminal, and restart the extension. The editor-spawned process will pick up the refreshed credentials.
Check your working directory
Claude Code can fail to initialize when the project path contains spaces, sits on a network or remote drive, or lives inside macOS's Documents folder, which has additional sandbox restrictions.
| Problem path | Fix |
|---|---|
Spaces in folder names (e.g., My Projects) | Rename to a space-free path or move the project to a simpler location. |
| Remote or network drive | Move the project to a local disk (for example, the root of C:\ on Windows). |
| macOS Documents folder | Move the project outside Documents, for example to ~/dev/. |
| VMware or virtualized filesystem | Test on a native filesystem to confirm the VM layer is not the cause. |
Confirm Git and runtime dependencies are installed
Claude Code relies on Git being available on the system path. Uninstalling Git, even accidentally during disk cleanup, will cause the process to exit immediately with code 1.
Step 1: Run git --version in a terminal. If the command is missing or returns an error, reinstall Git from git-scm.com.
Step 2: Verify Node.js with node -v. An outdated version can break the SDK. Update from nodejs.org if it is behind the Claude Code requirement.
Step 3: Restart your shell so new PATH entries take effect, then relaunch Claude Code.
Run claude doctor
The CLI ships with a diagnostic command that checks authentication, configuration, and environment prerequisites in one pass.
claude doctor
Run the built-in diagnostic
Review the output for any red or warning lines. It is faster than guessing and usually identifies missing dependencies, misconfigured API keys, or invalid settings before you start reinstalling anything.
Delete the crashing session instead of editing state files
If new sessions crash instantly while older ones resume fine, a specific task thread is likely in a stuck state. This is especially common after manually editing memory or context files inside the application's support folder.
Step 1: Open the Claude Code or desktop app UI and locate the task or session thread you were in when the crashes began.
Step 2: Delete that thread through the UI. Do not delete files directly from ~/Library/Application Support/Claude/ or its Windows equivalent.
Step 3: Start a new session in the same project. It should load cleanly.
Reinstall Claude Code cleanly
When the installation itself is corrupted (including after failed auto-updates), a clean reinstall is more reliable than trying to repair it in place.
Step 1: Uninstall the current CLI. For the Node package, run npm uninstall -g @anthropic-ai/claude-code.
Step 2: Remove leftover config directories for your OS (for example ~/.claude), keeping a backup of anything you need.
Step 3: Reinstall with npm install -g @anthropic-ai/claude-code and authenticate again by running claude.
SDK-specific crashes
When you see the error from the TypeScript or Python SDK rather than an editor, the cause is usually code-level rather than account-level.
| Trigger | What happens | Fix |
|---|---|---|
| VS Code debug terminal | SDK runs fine in a normal shell but crashes with exit 1 under the attached debugger. | Run the SDK process in a non-debug terminal, or detach the debugger from the child process. |
| Grep tool returning 100K+ matches | The internal ripgrep child times out, AbortController fires, and the SDK subprocess terminates. | Pass a head_limit to Grep calls and prefer output_mode: "files_with_matches" for broad patterns. |
| Parent app crash on SDK exit | One query failure tears down the whole application. | Catch the exit error at the wrapper level and return an empty response instead of rethrowing. |
Defensive handling in a TypeScript wrapper looks like this:
try {
return await claude.query(prompt);
} catch (error) {
const msg = error instanceof Error ? error.message : String(error);
if (msg.includes("Claude Code process exited with code 1")) {
logger.warn("Claude Code subprocess crashed; returning empty response.");
return { content: "" };
}
throw error;
}
Swallow SDK crashes without killing the parent process
Desktop app: when the bundled binary works but the app does not
On the macOS desktop app, there are cases where the bundled claude binary runs correctly when invoked directly from Terminal with the same flags, but crashes instantly when the app spawns it as a child process. Messages show "working" briefly, then disappear with no response, and main.log records the exit code 1 line on every attempt.
This pattern points to how the desktop app passes environment, authentication, or plugin parameters into the subprocess, not to the binary itself. Common workarounds that do not fix it include clearing caches, re-downloading the app, resetting the application support folder, re-logging in, resetting Xcode command line tools, and installing Rosetta 2. When you hit this specific variant, the productive path is to:
- Keep using the standalone CLI (
claudein a terminal) for active work. - File a bug with the exact desktop version, bundled binary version, and the contents of
main.logplus any CSP violations shown inunknown-window.log. - Wait for a patched desktop build rather than deleting credentials repeatedly.
Do not confuse this with hook exit code 1
If you are writing Claude Code hooks, exit code 1 from your hook script has a specific meaning that is unrelated to the crash error. A hook that exits with code 1 does not block the tool call. It only logs an error in the transcript and lets the action proceed.
| Hook exit code | Behavior |
|---|---|
| 0 | Action proceeds. Stdout is injected into context for UserPromptSubmit and SessionStart. |
| 2 | Action is blocked. Stderr is sent to Claude as feedback. |
| Any other non-zero (including 1) | Action proceeds, error is logged. Does not block. |
If you wrote a safety hook to block dangerous commands and it exits with 1, rewrite it to exit with 2. That is the only non-zero code that actually stops the tool from running.
When nothing works
If you have accepted terms, re-authenticated, moved your project to a clean path, confirmed Git and Node are installed, deleted the crashing session, and reinstalled the CLI, the remaining failure modes are usually version regressions tied to a specific extension build. Temporarily pin to a known-good version (for example, rolling the VS Code extension back to the last version that worked for you) and file an issue on the Claude Code GitHub repository with your logs, versions, and reproduction steps.
The error message never gets more specific than "process exited with code 1", but the fix almost always is: accepted terms, a valid authentication, a sane working directory, and an intact installation. Work through those four in order before reaching for anything heavier.