CClaude Code Guide中文

Claude Code troubleshooting

Troubleshooting Claude Code works best when you separate installation, authentication, configuration, permissions, external tools, and repository-specific failures.

Last verified
Applies to
Claude Code 2.1.x. CLI spellings were checked on local version 2.1.198; current official docs may describe newer 2.1.x behavior.
Verification method
Official documentation, CLI reference, and changelog reviewed on 2026-07-19. Version and help surfaces were checked locally. Doctor, auth, network, provider, and IDE outcomes vary by machine and are not presented as pre-run results.
Official sources
TroubleshootingAdvanced setupCLI referenceChangelog

Reproducible practice

Separate machine, account, customization, and repository failures

Use a fixed diagnostic ladder to find the first failing layer before changing prompts or reinstalling.

Prerequisites

  • The exact symptom, time, command, working directory, and first actionable error.
  • Permission to run read-only diagnostics and create a temporary empty directory.
  • A redaction plan for usernames, paths, tokens, repository names, and debug logs.

Steps

  1. Identify the executable and version

    A different shell or duplicate installation can explain behavior before project settings are involved.

    Step 1
    command -v claude
type -a claude 2>/dev/null || true
claude --version

  2. Check installation and authentication separately

    Doctor is read-only diagnostics; auth status answers a different question.

    Step 2
    claude doctor
claude auth status --text

  3. Compare safe mode and an empty directory

    Create a unique empty directory in the same shell. If the symptom disappears without customizations or outside the repository, inspect project settings, hooks, MCP, plugins, or memory before reinstalling.

    Step 3
    DIAGNOSTIC_DIR=$(mktemp -d "${TMPDIR:-/tmp}/claude-diagnostic.XXXXXX")
printf '%s\n' "$DIAGNOSTIC_DIR"
cd "$DIAGNOSTIC_DIR"
claude --safe-mode

  4. Collect narrow debug evidence

    Enable only relevant categories, write to a controlled file, and redact it before sharing.

    Step 4
    claude --debug "api,hooks" --debug-file ./claude-debug.log

Expected result

The symptom is assigned to an executable/install, authentication/provider, customization, repository, or external-service layer with a reproducible next check.

Validation

  • Repeat the original action after changing only one suspected layer.
  • Compare behavior in the original repo, safe mode, and an empty directory.
  • Record what remains unverified instead of declaring a root cause from correlation.

Failure handling

Claude will not start

Use shell-level claude doctor and inspect PATH before interactive commands.

Safe mode fixes it

Re-enable one customization class at a time: settings, hooks, MCP, plugins, then memory.

Both environments fail

Check account/provider status, network/TLS, and the official error reference before editing repository config.

Cleanup or rollback

  • After redaction and review, return to the original directory, verify DIAGNOSTIC_DIR is the printed mktemp path, then remove only that directory.
  • Restore one configuration change at a time; keep a backup of malformed settings before repair.

Boundaries and when not to use it

  • Debug logs can contain sensitive paths and request context. Do not publish them unredacted.
  • Doctor reporting Search as OK does not rule out WSL cross-filesystem performance or incomplete search results.

Installation and version checks

Confirm the CLI is installed, available on PATH, and updated through the installation method you used. Different installation channels may update differently.

Authentication checks

If sessions cannot start, verify login state and account access before debugging project settings. Authentication failures can look like tool or model problems if skipped.

Configuration loading

When instructions, permissions, hooks, or MCP servers do not apply, inspect what the current session actually loaded. The issue is often path, scope, or config precedence.

Repository failures

For build or test failures after a change, keep the failing command output visible and ask Claude Code to trace from the first actionable error rather than rewriting unrelated code.

Diagnostic commands
claude doctor
claude auth status --text
claude --debug "api,hooks"

Common failure categories

Most issues fall into a small set of categories. Diagnose them in order instead of changing prompts first.

CLI not found

Reinstall with `claude install`, confirm PATH, and compare against duplicate installs reported by doctor.

Read guide

Auth expired

Run auth status, re-login, and verify the account has access to the intended product surface.

Read guide

Troubleshooting checklist

Related topics

SetupAuthenticationSettingsCI/CD