Troubleshooting

Start with the Doctor. Then match your symptom to the table.

Doctor

CodeBuddy: Run Doctor

Automated diagnostics covering the extension’s invariants. Each check surfaces critical / warn / info — some carry an auto-fix flag runnable via CodeBuddy: Doctor Auto-Fix.

Check	Verifies
API key audit	Keys configured + valid for the selected provider
Input validator	Injection guard functioning
Terminal restrictions	Dangerous command patterns block correctly
Directory permissions	Workspace + .codebuddy/ writable
MCP configuration	Server configs valid, servers reachable
Security configuration	Permission profile + access control coherent
Credential proxy	Proxy running + responding (when enabled)
Permission scope	Tool allow/block lists consistent
Access control	Identity resolution + access mode working

Doctor can also run silently via runBackground() and surface findings in the status bar.

Common symptoms

”API key not configured”

Cause: no key set for the selected provider.

Fix: the onboarding wizard is the easiest path. Or set the setting directly:

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

Or via env:

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

Provider setting keys are documented on the Configuration page.

”MCP server failed to start”

Cause: invalid server command, missing deps, Docker not running (for Docker gateway), or a stdio server whose approval was denied.

Fix, in order:

1. Check the codebuddy.mcp.servers setting in settings.json — syntax + command validity.
2. Node.js 18+ installed for stdio servers.
3. For Docker gateway: docker info must succeed.
4. Test the command manually: npx -y @your-org/mcp-server.
5. Circuit breaker: after 3 consecutive failures a server is OPEN for 5 min. Wait or CodeBuddy: Reset MCP Server Approvals + reload.

”Tool call denied”

Cause: permission profile blocks the tool, OR auto-approve is off and you missed the prompt.

Fix: approve inline when prompted, change profile (codebuddy.permissionScope.defaultProfile), or turn on blanket auto-approval:

{
  "codebuddy.autoApprove": true,
  "codebuddy.permissionScope.defaultProfile": "standard"
}

“Forced stop: max tool invocations”

Cause: hit the 2000 tool-call safety guard. Almost always a loop.

Fix:

• Task too vague — provide more specific instructions.
• Same file edited repeatedly — the file-edit loop detector trips at codebuddy.agent.fileEditLoopThreshold same-file edits (default 20).
• Project rules conflict with the task — review .codebuddy/rules.md.

Raising limits is a last resort:

{
  "codebuddy.agent.maxToolInvocations": 3000,
  "codebuddy.agent.maxEventCount": 20000
}

“Provider failover active”

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

Fix: CodeBuddy automatically switches to a backup. Meanwhile check:

• API key valid + credits available
• Not exceeding provider rate limits
• Provider status page for outages

Cooldowns: rate_limit 1 min · auth 10 min · billing 30 min · overloaded 2 min · model_not_found 1 hr.

”Task exceeded cost limit”

Cause: the conversation’s estimated spend exceeded codebuddy.agent.costThreshold (USD per conversation, default 1000), or the daily codebuddy.agent.dailySpendCap.

Fix: raise the threshold or pick a cheaper model (set the active provider’s <provider>.model, e.g. openai.model):

{
  "codebuddy.agent.costThreshold": 2000,
  "openai.model": "gpt-4o-mini"
}

Extension not loading

1. Editor version — requires VS Code 1.78+ or compatible.
2. Other AI extensions conflicting? Disable to test.
3. Output > CodeBuddy panel for error logs.
4. CodeBuddy: Run Doctor.
5. .codebuddy/logs/*.log for detailed structured logs.

Log files

.codebuddy/logs/codebuddy-{date}.log — one JSON event per line:

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

1000-entry in-memory circular buffer + on-disk log file. traceId matches the active OTel trace for correlation with Telemetry.

Reset commands

Situation	Command
MCP server config changed	CodeBuddy: Reset MCP Server Approvals
Skill installer prompted for the wrong file	CodeBuddy: Reset Skill Installer State
Detected identity wrong (team mode)	CodeBuddy: Reset Access Cache
Workspace analysis guessed wrong	CodeBuddy: Reset Workspace Analysis
Something unclear	CodeBuddy: Run Doctor

Getting help

• GitHub issues: github.com/olasunkanmi-SE/codebuddy/issues
• Security issues: do NOT open a public issue — email the maintainer directly (see package.json publisher).
• Discussions: GitHub Discussions on the repo.