Claude Code Guide

Apparence

Guide de résolution des problèmes courants.

Total: 16 problèmes documentés

API ​

API key not recognized ​

Sévérité: 🔴 Critical

Symptôme: Error: Invalid API key or authentication failed

Cause: Missing or incorrect ANTHROPIC_API_KEY environment variable

Solution:

  1. Generate API key from console.anthropic.com
  2. Set environment variable: export ANTHROPIC_API_KEY="sk-ant-..."
  3. Add to ~/.bashrc or ~/.zshrc for persistence
  4. Restart terminal or source config file

Commande de correction:

bash
export ANTHROPIC_API_KEY="sk-ant-your-key-here"
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc

Context ​

Context window overflow ​

Sévérité: 🟡 Medium

Symptôme: Error: Context limit exceeded, conversation too long

Cause: Too many files loaded, large CLAUDE.md, or lengthy conversation history

Solution:

  1. Use /compact to compress history
  2. Use /context stats to check usage
  3. Add patterns to .claudeignore
  4. Split large CLAUDE.md into .claude/rules/
  5. Clear conversation with /clear

Commande de correction:

bash
/compact
/context stats
/clear

Git ​

Git operations failing in Claude ​

Sévérité: 🟡 Medium

Symptôme: Git push/pull/merge commands error or get stuck

Cause: Merge conflicts, detached HEAD, or uncommitted changes blocking operations

Solution:

  1. Check git status manually
  2. Resolve conflicts outside Claude first
  3. Ensure clean working directory
  4. Use claude commit for commits
  5. Handle complex git operations manually
  6. Review permissions for .git directory

Commande de correction:

bash
git status
git stash
claude commit

Hooks ​

Hook not triggering ​

Sévérité: 🟡 Medium

Symptôme: Hook script exists but never executes

Cause: Incorrect matcher pattern, missing execute permissions, or wrong settings.json structure

Solution:

  1. Verify hook script has execute permissions (chmod +x)
  2. Check matcher pattern in settings.json
  3. Test hook event is actually firing
  4. Review hook JSON structure
  5. Check hook output with verbose logging
  6. Verify hook location (user vs project)

Commande de correction:

bash
chmod +x ~/.claude/hooks/my-hook.sh
# Check settings.json structure

Installation ​

Installation fails on macOS/Linux ​

Sévérité: 🟠 High

Symptôme: curl command fails or installation script errors

Cause: Network issues, permissions, or incompatible shell

Solution:

  1. Check internet connection
  2. Run with sudo if needed
  3. Verify bash/zsh compatibility
  4. Try manual download from GitHub releases

Commande de correction:

bash
curl -fsSL https://claude.ai/install.sh | bash

Command 'claude' not found ​

Sévérité: 🟠 High

Symptôme: bash: claude: command not found or zsh: command not found: claude

Cause: Command not found in PATH, incomplete installation, or shell profile not loaded

Solution:

  1. Restart terminal after installation
  2. Source shell config: source ~/.bashrc or source ~/.zshrc
  3. Check PATH: echo $PATH
  4. Reinstall Claude Code
  5. Verify installation location: which claude
  6. Add to PATH manually if needed

Commande de correction:

bash
source ~/.bashrc
# Or
source ~/.zshrc
# Check installation:
which claude

LSP ​

LSP server not starting ​

Sévérité: 🟡 Medium

Symptôme: No diagnostics, goToDefinition fails, hover not working

Cause: Missing .lsp.json config, LSP server not installed, or incorrect command path

Solution:

  1. Install LSP server (e.g., npm install -g @vtsls/language-server)
  2. Create .lsp.json at plugin root
  3. Verify command path and args
  4. Check extensionToLanguage mappings
  5. Restart Claude Code

Commande de correction:

bash
npm install -g @vtsls/language-server
# Create .lsp.json with proper config

MCP ​

MCP server connection failed ​

Sévérité: 🟠 High

Symptôme: MCP tools not available, OAuth fails, connection timeout

Cause: Server not configured, invalid URL, network issues, or missing authentication

Solution:

  1. Use /mcp to check server status
  2. Verify URL and transport type (http/sse/stdio)
  3. Check OAuth authentication
  4. Test network connectivity
  5. Review .mcp.json configuration
  6. Use claude mcp list to view servers

Commande de correction:

bash
/mcp
claude mcp list
claude mcp get `<server-name>`

Memory ​

CLAUDE.md not being loaded ​

Sévérité: 🟡 Medium

Symptôme: Claude doesn't follow instructions from CLAUDE.md

Cause: File in wrong location, incorrect filename, or not in current directory hierarchy

Solution:

  1. Use /memory to check loaded files
  2. Verify filename: CLAUDE.md (exact case)
  3. Check file location: project root or .claude/
  4. For local overrides: CLAUDE.local.md
  5. Review .claude/rules/ structure
  6. Restart Claude Code session

Commande de correction:

bash
/memory
# Check file exists at correct path

Modes ​

Cannot switch to Plan Mode ​

Sévérité: 🟢 Low

Symptôme: Shift+Tab doesn't work or stuck in Normal/Auto mode

Cause: Not pressing Shift+Tab or incorrect mode sequence

Solution:

  1. Use Shift+Tab to cycle: Normal → Auto → Plan → Normal
  2. Check terminal keybinding support
  3. Use --permission-mode plan CLI flag as alternative
  4. Verify status indicator at bottom of terminal
  5. Run /terminal-setup for iTerm2/VS Code
  6. Restart Claude Code if stuck

Commande de correction:

bash
claude --permission-mode plan
Shift+Tab (press twice from Normal mode)

Network ​

Cannot connect to Anthropic API ​

Sévérité: 🟠 High

Symptôme: Connection timeout, network errors, or SSL certificate issues

Cause: Corporate firewall, proxy settings, or network restrictions blocking claude.ai/anthropic.com

Solution:

  1. Check internet connectivity
  2. Configure proxy if behind corporate firewall
  3. Set HTTP_PROXY and HTTPS_PROXY environment variables
  4. Check firewall rules for anthropic.com
  5. Try different network connection
  6. Contact IT for API access permissions

Commande de correction:

bash
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

Performance ​

Claude Code running very slowly ​

Sévérité: 🟡 Medium

Symptôme: Long delays between responses, slow file operations

Cause: Large files in context, too many file reads, or inefficient CLAUDE.md

Solution:

  1. Use .claudeignore to exclude large files/directories
  2. Reduce CLAUDE.md size, split into .claude/rules/
  3. Clear conversation history with /clear
  4. Use /compact to reduce context
  5. Avoid loading unnecessary files
  6. Check network latency if using remote models

Commande de correction:

bash
/compact
/clear
# Add to .claudeignore: node_modules/, dist/, *.log

Permissions ​

Permission denied on file operations ​

Sévérité: 🟠 High

Symptôme: Claude cannot write/edit files, permission errors

Cause: File permissions, write access restricted, or blocked by settings.json

Solution:

  1. Check file/directory permissions
  2. Review .claude/settings.json deny rules
  3. Use /permissions to audit configuration
  4. Add file patterns to allow list
  5. Verify additionalDirectories setting

Commande de correction:

bash
/permissions
chmod u+w filename.txt

Skills ​

Skill not being invoked ​

Sévérité: 🟡 Medium

Symptôme: Skill exists but Claude never uses it

Cause: Poor description field in SKILL.md, missing trigger keywords, or file not in correct location

Solution:

  1. Improve description with specific trigger terms
  2. Verify SKILL.md location: ~/.claude/skills/ or .claude/skills/
  3. Check YAML frontmatter: name and description required
  4. Keep SKILL.md body under 500 lines
  5. Test with explicit mention in prompt
  6. Restart Claude Code session

Commande de correction:

bash
# Explicitly mention skill in prompt:
"Use the [skill-name] skill to process this PDF"

Sub-Agents ​

Sub-agent not invoking automatically ​

Sévérité: 🟡 Medium

Symptôme: Sub-agent exists but Claude never calls it

Cause: Poor description field, missing/vague trigger keywords, or incorrect agent file location

Solution:

  1. Improve description with specific trigger terms
  2. Add clear use-case keywords
  3. Verify file location: ~/.claude/agents/ or .claude/agents/
  4. Check YAML frontmatter format
  5. Test with explicit invocation first
  6. Review name field uniqueness

Commande de correction:

bash
# Use explicit invocation to test:
"Use the [agent-name] subagent to analyze this"

Thinking ​

Ultrathink not working as expected ​

Sévérité: 🟢 Low

Symptôme: No visible extended thinking, or thinking budget not increasing

Cause: MAX_THINKING_TOKENS set but ultrathink keyword used, or conflicting configurations

Solution:

  1. Check if MAX_THINKING_TOKENS is set (overrides ultrathink)
  2. Unset MAX_THINKING_TOKENS if using ultrathink keyword
  3. Use /config to enable extended thinking
  4. Verify with Ctrl+O to see thinking output
  5. Remember: ultrathink only works without MAX_THINKING_TOKENS
  6. Use explicit keywords: 'ultrathink' or 'think harder'

Commande de correction:

bash
unset MAX_THINKING_TOKENS
/config
Ctrl+O

Guide créé avec Claude Code - Preuve de concept des techniques enseignées

Contenu basé sur la documentation officielle Anthropic