Skip to content

Troubleshooting

Doctor command

Section titled “Doctor command”

Run the built-in diagnostic tool to verify your setup:

CodeBuddy: Run Doctor

Doctor executes 9 automated checks and reports findings with severity levels:

CheckWhat it verifies
API key auditAPI keys are configured and valid for the selected provider
Input validatorInput guard is functioning (prevents injection)
Terminal restrictionsDangerous command patterns are properly blocked
Directory permissionsWorkspace and .codebuddy/ directories are writable
MCP configurationMCP server configs are valid and servers are reachable
Security configurationPermission profile and access control are properly set
Credential proxyProxy is running and responding (if enabled)
Permission scopeTool allowlist/blocklist is consistent
Access controlUser identity resolution and access mode are working

Finding severity levels

Section titled “Finding severity levels”
LevelMeaning
criticalSomething is broken and must be fixed
warnPotential issue that may cause problems
infoInformational — no action needed

Some findings include an auto-fix flag. Run CodeBuddy: Doctor Auto-Fix to apply automatic corrections.

Doctor can also run silently in the background (runBackground()) and show alerts in the status bar without interrupting your workflow.

Common issues

Section titled “Common issues”

”API key not configured”

Section titled “”API key not configured””

Cause: No API key set for the selected provider.

Fix: Open settings and add your API key:

{
  "codebuddy.anthropic.apiKey": "sk-ant-..."
}

Or set it via environment variable:

Terminal window
export CODEBUDDY_ANTHROPIC_API_KEY="sk-ant-..."

“MCP server failed to start”

Section titled ““MCP server failed to start””

Cause: The MCP server command is invalid, dependencies are missing, or Docker is not running.

Fix:

  1. Check your server configuration in .codebuddy/mcp.json
  2. Ensure Node.js 18+ is installed (for stdio servers)
  3. For Docker gateway: verify Docker Desktop is running with docker info
  4. Test the server command manually:
    Terminal window
    npx -y @your-org/mcp-server
  5. Check the circuit breaker — if a server failed 3+ times, it enters a 5-minute cooldown. Wait or restart the extension.

”Task exceeded cost limit”

Section titled “”Task exceeded cost limit””

Cause: The task consumed more tokens than the configured codebuddy.costLimit.

Fix: Increase the limit or use a more cost-efficient model:

{
  "codebuddy.costLimit": 5.0,
  "codebuddy.defaultModel": "gpt-4o-mini"
}

“Tool call denied”

Section titled ““Tool call denied””

Cause: The active permission profile blocks the tool, or auto-approve is off.

Fix: Either approve the tool call when prompted, change the permission profile, or add the tool to auto-approve:

{
  "codebuddy.autoApproveTools": ["read_file", "edit_file"],
  "codebuddy.security.permissionProfile": "standard"
}

“Forced stop: max tool invocations”

Section titled ““Forced stop: max tool invocations””

Cause: The agent hit the 400 tool-call safety limit or the 2,000 event limit.

Fix: This usually means the agent is looping. Check if:

  • The task is too vague — provide more specific instructions
  • A file is being edited repeatedly — the file edit loop detector triggers at 4 edits to the same file
  • Project rules conflict with the task — review .codebuddy/rules.md

You can increase limits (not generally recommended):

{
  "codebuddy.agent.maxToolInvocations": 600,
  "codebuddy.agent.maxEvents": 3000
}

“Provider failover active”

Section titled ““Provider failover active””

Cause: The primary LLM provider is returning errors (429, 503, auth failure, etc.).

Fix: CodeBuddy automatically fails over to backup providers. Check:

  • Your API key is valid and has sufficient credits
  • You haven’t exceeded the provider’s rate limit
  • The provider’s status page for outages

Cooldown durations: rate limit (1 min), auth (10 min), billing (30 min), overloaded (2 min).

Extension not loading

Section titled “Extension not loading”
  1. Check editor version (requires 1.96.0+ or equivalent)
  2. Disable other AI extensions that may conflict
  3. Check the Output panel → CodeBuddy for error logs
  4. Run CodeBuddy: Run Doctor for diagnostics
  5. Check .codebuddy/logs/ for detailed agent logs

Log files

Section titled “Log files”

Agent logs are written to .codebuddy/logs/codebuddy-{date}.log with structured JSON entries:

{
  "timestamp": "2026-03-26T10:30:00.000Z",
  "level": "ERROR",
  "module": "MCPService",
  "message": "Connection failed",
  "traceId": "abc123",
  "sessionId": "def456"
}

Logs use a 1,000-entry circular buffer and include OpenTelemetry trace IDs for distributed debugging.

Getting help

Section titled “Getting help”