Claude Code Troubleshooting: Fixes That Actually Work

When Claude Code troubleshooting begins, resist the urge to reinstall immediately. Most incidents fall into a short list: auth, network, permissions, or tool conflicts. Work the list top-down and retry after each change.

Step 1 — Capture the symptom

Save the exact error text, timestamp, OS version, and whether VPN is on. Screenshots help; log snippets help more.

Step 2 — Account and session

Sign out and sign in.
Confirm plan status in the Anthropic console.
Try a personal hotspot to isolate corporate firewall issues.

Step 3 — Network and proxy

SSL inspection and missing root CAs cause mysterious failures. IT may need to allowlist endpoints or provide a trusted proxy config. See our login guide for OAuth-specific tips.

Step 4 — Local environment

Run from the repo root with clean git status when testing.
Disable other AI extensions temporarily.
Verify disk space and file permissions on the project directory.

Step 5 — Reinstall (last resort)

Download a fresh copy from claude.com/download, uninstall, reboot, reinstall. Export rules first.

When to escalate

If multiple machines on the same network fail identically, involve IT with domain allowlists. If only one repo fails, suspect hooks, submodules, or enormous generated folders — add ignore rules.