Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
97 lines (77 loc) · 3.84 KB

TROUBLESHOOTING.md

File metadata and controls

97 lines (77 loc) · 3.84 KB
Raw

Troubleshooting

Setup

"Config file not found"

Run agora init to create a config in .ca/config.json.

"API key not found for provider 'openrouter'"

  1. Get a key at openrouter.ai
  2. Set it: export OPENROUTER_API_KEY=your_key_here
  3. Verify: agora doctor

Provider environment variable names follow the pattern PROVIDER_API_KEY where possible (e.g., OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY). Run agora providers to see all supported providers and their required env vars.

"doctor passes but review fails with API error"

  • Run agora doctor --live to test actual API connectivity
  • Check if your API key is expired or rate-limited
  • Check your OpenRouter key budget and provider/model availability

"JSON parse error in .ca/config.json"

Your config file has a syntax error. Options:

  1. Edit manually: open .ca/config.json in your editor and fix the syntax
  2. Regenerate: delete .ca/ and run agora init again
  3. Validate: paste your config into jsonlint.com

Review

"All reviewers failed"

All configured LLM providers returned errors. Common causes:

  • API keys missing: Run agora doctor to check
  • Network issues: Check your internet connection
  • Rate limiting: Wait a few minutes and retry
  • Invalid model: Check your config for typos in model names

Empty output (no issues found)

If the diff contains no code changes (only whitespace, comments, or empty), the pipeline returns ACCEPT with "No code changes detected."

Review takes too long (15+ minutes)

  • Use quick mode: agora review --quick (L1 only, no debate)
  • Reduce reviewers: agora review --reviewers 2
  • Large diffs are automatically chunked; consider splitting your PR

"Not in a git repository"

CodeAgora uses git for context-aware reviews. Run from within a git repo, or provide an explicit diff file:

agora review path/to/my.diff

GitHub Actions

For a complete setup checklist, recommended workflow snippets, provider secrets, permissions, and context-limit guidance, see GitHub Actions Setup Guide.

Fork PR review skipped

Fork PRs don't have access to repository secrets. The review will be skipped with a warning. Options:

  1. Ask the maintainer to run the review manually
  2. Configure Actions for forks

"max-diff-lines exceeded"

The PR diff exceeds the configured limit (default: 5000 lines). Options:

  1. Split into smaller PRs
  2. Increase the limit in your workflow: 
    with:
  max-diff-lines: '10000'

MCP Integration

"CodeAgora MCP not available in Claude Code"

  1. Verify your MCP config (~/.claude/mcp.json): 
    {
  "mcpServers": {
    "codeagora": {
      "command": "npx",
      "args": ["-y", "@codeagora/mcp"]
    }
  }
}
  2. Restart Claude Code
  3. Check that npx -y @codeagora/mcp starts without errors

"repo_path is outside the allowed repository boundary"

  • repo_path is optional, but when provided it must point to the exact workspace root or a real directory inside the current repository checkout.
  • Symlinks and paths outside the repo are rejected on purpose so MCP tools do not read or write unrelated files.
  • If you only need the current workspace, omit repo_path and let the server use its current working directory.
  • The MCP error body now includes guidance with the same retry hint.

Exit Codes

Code Meaning CI Action
0 Review command completed and no requested failure gate tripped Pipeline continues
1 --fail-on-reject or --fail-on-severity tripped Pipeline fails
2 Setup/input/config error Fix setup or command arguments
3 Runtime or pipeline failure May be transient, retry