Aller au contenu principal

Troubleshooting Guide

Solve common problems with Claude Code and the claude-base foundation

Sections​

1. Common Claude Code problems​

SymptomProbable causeSolution
"Context window full" or automatic compactionToo many files read, long session, verbose logs included/compact to summarize, avoid reading /tmp/ or node_modules/
Very slow session, high token countRepeated reading of large files, uncompacted context/compact between phases, use effort low for exploration
Silent hook that does not triggerNon-executable script, wrong path, timeout exceededCheck the logs in /tmp/claude-sessions.log, test the script manually
MCP server missing or disconnectedServer disabled in .mcp.json, missing dependencyCheck "disabled": true in .mcp.json, restart with /mcp
Agent or skill that does not triggerWrong namespace, description too vague, missing fileCheck the exact name with /help, read the description in the .md file
Permission refusal loopCommand in the deny list of settings.json, strict auto mode/less-permission-prompts to optimize allowlists, or SKIP_COMMAND_VALIDATOR=1
Too many permission promptsPermissions too restrictive for the workflow/less-permission-prompts scans transcripts and proposes optimized allowlists
Git conflict during the TDD cycleBranch out of sync, missing intermediate commitgit stash, git pull --rebase, then git stash pop
claude not found or Node errors after claude updateMigration to the native binary (CLI 2.1.113+): the CLI is no longer a JavaScript bundleReinstall via the official channel, check which claude and claude --version. Old aliases pointing to node /path/to/cli.js no longer work
Subagent that "hangs" without returningBefore CLI 2.1.113: silent hang possibleUpdate: subagents idle > 10 min now fail with a clear message
Permission dialog that crashes when a teammate requests a toolCLI bug prior to 2.1.114Update to CLI >= 2.1.114
Truncated responses, incoherent reasoning, degraded quality between March 4 and April 10 2026Cumulative regression: default medium effort, broken thinking history caching, system prompt limiting to 25 words between tool callsResolved in v2.1.101 (April 10 2026). Run claude update; the default effort returns to high and caching is fixed

Context window full​

Automatic compaction triggers when the context approaches the limit. If it fails or is mistimed:

# Compact manually between two phases
/compact

# If the context is corrupted or too fragmented
/clear

To avoid in order to reduce pressure on the context: reading entire directories (node_modules/, .git/, dist/), including large log files, re-reading already known files.

MCP servers​

MCP servers are disabled by default in .mcp.json. To diagnose:

# Check the state of MCP servers
cat .mcp.json | grep -A3 "disabled"

# Read MCP events
cat /tmp/claude-mcp.log

To enable a server, remove "disabled": true or change it to "disabled": false in .mcp.json.

2. Foundation problems​

Pre-commit tests blocking a commit​

The PreToolUse hook intercepts git commit and runs the tests. If the tests fail, the commit is blocked.

Diagnosis:

# Run the tests manually to see the errors
npm test

# Or depending on the project
pytest
go test ./...
flutter test

If the tests fail legitimately (known technical debt, work in progress):

# Disable pre-commit tests for this commit only
SKIP_PRE_COMMIT_TESTS=1 git commit -m "wip: ..."

If the hook is faulty (missing Husky, script not found):

Claude Code automatically detects and repairs Husky if necessary. In case of persistent failure, check:

ls -la .husky/
cat /tmp/claude-sessions.log | tail -20

Main branch protection​

The PreToolUse hook blocks any direct modification on main or master. This is an intentional safeguard.

Normal solution: work on a feature branch.

git checkout -b feature/my-modification

If a direct modification on main is absolutely necessary (critical hotfix, personal repository):

ALLOW_MAIN_EDIT=1 git commit -m "fix: critical hotfix"

Gitleaks: false positives​

The secret detection hook analyzes content before each write. It may flag false positives on test tokens, configuration examples, or placeholders.

Identify the detected pattern:

# Test gitleaks directly on the file in question
gitleaks detect --source . --verbose 2>&1 | grep -A5 "leak"

Add an exception in .gitleaks.toml (at the project root, create if absent):

[allowlist]
  description = "Known false positives"
  regexes = [
    '''EXAMPLE_TOKEN_FOR_TESTS''',
    '''placeholder_api_key'''
  ]
  paths = [
    '''tests/fixtures/.*''',
    '''docs/.*'''
  ]

Formatting hooks that break the code​

The PostToolUse hooks run Prettier, Ruff, gofmt, etc. after each write. If the formatter is missing or misconfigured, it may produce empty output or a silent error.

Check that the formatter is installed:

# TypeScript/JavaScript
npx prettier --version

# Python
ruff --version || black --version

# Go
gofmt --version

# Dart
dart format --help

If the formatter modifies the code too aggressively:

Check the local configuration (.prettierrc, pyproject.toml, .editorconfig). The formatter uses the project configuration if it exists.

Command validator blocking a legitimate command​

The Command validator hook analyzes 8 risk categories. Some valid commands may match a dangerous pattern.

Identify why the command is blocked:

# Read the session logs to see the blocking reason
cat /tmp/claude-sessions.log | grep -i "block\|validator" | tail -10

Bypass for a specific command:

SKIP_COMMAND_VALIDATOR=1 <command>

Bypass permanently for a session:

Add in .claude/settings.local.json (not committed):

{
  "env": {
    "SKIP_COMMAND_VALIDATOR": "1"
  }
}

3. Quick diagnosis​

Use this decision tree to quickly identify the source of a problem.

MY COMMIT IS BLOCKED
│
├── "tests failed" message?
│   ├── Yes → npm test (or equivalent) to see the errors
│   │         Fix the tests OR SKIP_PRE_COMMIT_TESTS=1
│   └── No
│       ├── "branch main protected" message?
│       │   └── Yes → Create a branch OR ALLOW_MAIN_EDIT=1
│       ├── "secret detected" message?
│       │   └── Yes → Remove the secret OR add exception .gitleaks.toml
│       └── Other → cat /tmp/claude-sessions.log | tail -30


CLAUDE NO LONGER RESPONDS / VERY SLOW
│
├── Long session (>1h, many files read)?
│   └── Yes → /compact (preserves the essential context)
├── Complete topic change?
│   └── Yes → /clear (start over)
├── Still slow even after /compact?
│   └── Yes → /clear + restart with a concise prompt
└── Claude seems stuck on a task?
    └── Ctrl+C to interrupt, then rephrase the request


THE AGENT / COMMAND DOES NOTHING
│
├── Is the name correct?
│   └── No → /help to list available commands
├── Is the agent waiting for parameters?
│   └── Possible → read the description: /work:work-plan "description"
├── Does the agent file exist?
│   └── Check: ls .claude/commands/
├── Model insufficient for the task?
│   └── Opus for complex tasks, Sonnet for audits
└── Sub-agent that does not start?
    └── cat /tmp/claude-agents.log | tail -20


THE HOOK DOES NOT TRIGGER
│
├── Check that the script is executable
│   └── ls -la .claude/hooks/
├── Test the script manually
│   └── bash .claude/hooks/my-script.sh
├── Check the logs
│   └── cat /tmp/claude-sessions.log | tail -30
└── Timeout too short?
    └── Check the "timeout" property in settings.json

4. Diagnostic commands​

CommandUseWhen to use it
/compactSummarizes the context while preserving the essentialLong session, between two workflow phases
/clearErases the entire contextTotal topic change, corrupted context
/rewindReturns to the last stable state before a modificationRefactoring that broke everything
/helpLists all available commands and agentsAgent not found, uncertain name
claude --versionDisplays the installed versionCompatibility issue, missing feature
cat /tmp/claude-sessions.logSession logs (startup, compaction, hooks)Silent hook, startup problem
cat /tmp/claude-agents.logSub-agent logsAgent that does not start or terminates prematurely
cat /tmp/claude-notifications.logPermission and waiting logsPermission refused, Claude waiting for the user
cat /tmp/claude-mcp.logMCP Elicitation logsMCP server disconnected, elicitation failed

Check the version and installation​

# Claude Code CLI version
claude --version

# Check that hooks are properly loaded at startup
cat /tmp/claude-sessions.log | head -20

# Check the permissions of hook scripts
ls -la .claude/hooks/

# Test a specific hook independently
bash .claude/hooks/pre-commit-tests.sh

Inspect logs in real time​

# Follow session logs live during a Claude session
tail -f /tmp/claude-sessions.log

# Follow agent logs live
tail -f /tmp/claude-agents.log

5. Emergency recovery​

/rewind: undo the latest modifications​

Claude Code automatically saves a checkpoint before each modification. In case of refactoring that breaks everything:

/rewind

This returns to the last stable state, faster than git stash or git checkout. Use it before the situation degrades further.

git stash + clean restart​

When current modifications are too complex to untangle:

# Save the current state
git stash push -m "wip: before clean restart"

# Return to the last clean commit
git status   # check that we are clean

# Restart Claude Code in a fresh state
/clear

To recover the saved work later:

git stash pop

Disable hooks temporarily​

If a hook persistently blocks the work, disable it via environment variables. Several methods:

For a single command:

SKIP_PRE_COMMIT_TESTS=1 git commit -m "..."
SKIP_PRE_PUSH_CI=1 git push
SKIP_COMMAND_VALIDATOR=1 <command>
SKIP_DESTRUCTIVE_CHECK=1 <command>

For an entire session (in .claude/settings.local.json, not committed):

{
  "env": {
    "SKIP_PRE_COMMIT_TESTS": "1",
    "ALLOW_MAIN_EDIT": "1"
  }
}

Available variables:

VariableEffect
ALLOW_MAIN_EDIT=1Disables main branch protection
SKIP_PRE_COMMIT_TESTS=1Disables tests before commit
SKIP_PRE_PUSH_CI=1Disables local CI before push
SKIP_COMMAND_VALIDATOR=1Disables security validation of commands
SKIP_DESTRUCTIVE_CHECK=1Disables protection against destructive operations

Fully reset the hooks​

If the hooks are in an inconsistent state (permissions, modified scripts):

# Reset hook permissions
chmod +x .claude/hooks/*.sh

# Check that the content of the hooks has not been altered
git diff .claude/hooks/

# Restore from git if necessary
git checkout .claude/hooks/

Unsolvable git conflict during TDD​

When a merge conflict blocks the TDD cycle:

# Abort the ongoing merge
git merge --abort
# or
git rebase --abort

# Return to a clean state
git checkout main
git pull --rebase origin main

# Recreate the working branch from a clean state
git checkout -b feature/new-attempt

Complete project cleanup (foundation + Claude Code state)​

The foundation install and Claude Code's runtime state for a project live in two distinct places. A "clean slate" usually means wiping both.

ToolScopeRemoves
bash scripts/uninstall.sh (or claude-base dispatcher's uninstall flow)Project-local foundation install<project>/.claude/, CLAUDE.md, CLAUDE.local.md, claude-base entries in .gitignore
claude project purge <path> (CLI 2.1.126+)Per-project Claude Code runtime state~/.claude/projects/<encoded-path>/ (transcripts, memory), ~/.claude/tasks/, ~/.claude/file-history/, ~/.claude/debug/, the project entry in ~/.claude.json

The two scopes do not overlap. uninstall.sh does not touch ~/.claude/; claude project purge does not touch the project directory. For a full teardown, run both:

# 1. Remove the foundation install from the project directory
bash scripts/uninstall.sh

# 2. Wipe Claude Code's runtime state for this project (preview first)
claude project purge --dry-run /path/to/project
claude project purge /path/to/project

claude project purge accepts --dry-run, -i (interactive per-item), -y (skip confirmation), and --all (every project, mutually exclusive with a path). The foundation's uninstall.sh is unchanged for backward compatibility — it prints a reminder pointing at claude project purge after a successful uninstall.

6. Performance optimization​

When to use /compact vs /clear​

SituationCommandReason
Long session, same topic/compactPreserves learned decisions and conventions
Between two workflow phases/compactKeeps the context of the plan and exploration
Switching to an unrelated feature/clearPrevents the old context from polluting the new one
Context window > 80% used/compactPreventive before saturation
Corrupted or inconsistent context/clearStart over on a clean basis

Rule: prefer /compact over /clear. Compaction preserves the essentials (decisions, conventions, project structure) whereas /clear erases everything and forces re-exploration.

Reduce token consumption​

Use the appropriate effort levels:

TaskRecommended effortCommand
Read and explore codeLow/effort low
Implement a standard featureMedium/effort medium
Design an architectureHigh/effort high
Critical audit, complex debugMaximum/effort max

Avoid expensive reads:

# Do not read entire directories
# Bad: read all of src/
# Good: target the relevant files

# Use grep before reading
grep -r "functionName" src/ --include="*.ts" -l
# then read only the relevant files

Enable RTK to reduce tokens by 60-90%:

In .claude/settings.local.json (not committed):

{
  "env": {
    "ENABLE_RTK": "1"
  }
}

Check the savings achieved:

rtk gain

Avoid reading large files​

Files and directories never to read in their entirety:

To avoidAlternative
node_modules/Read only package.json
dist/, build/, .next/Generated files, useless to read
/tmp/claude-*.log (entire)tail -20 /tmp/claude-sessions.log
yarn.lock, package-lock.jsonRead only package.json
.git/Use git commands

Structure sessions to minimize context​

  • One session = one feature or one bug. Do not mix topics.
  • Commit frequently: /compact is more effective on recent context.
  • Use /compact between workflow phases (after Explore, after Plan).
  • Limit the number of simultaneously open files to what is strictly necessary.

Resources​