Skip to content
AI Agent Docs Hub

Troubleshooting

Troubleshooting

Common problems and solutions for AI coding agent setups.

API Key Issues

Missing API Key

Error: API key not found or Authentication required

Fix:

  1. Confirm the environment variable is set:
    Terminal window
    echo $GEMINI_API_KEY
  2. If empty, export it:
    Terminal window
    export GEMINI_API_KEY="your-key"
  3. Persist it by adding to your shell profile:
    Terminal window
    echo 'export GEMINI_API_KEY="your-key"' >> ~/.bashrc
    source ~/.bashrc
  4. Restart your terminal or agent after setting the variable.

Invalid API Key

Error: 401 Unauthorized or Invalid API key

Fix:

  1. Verify the key hasn’t been revoked in the provider’s dashboard.
  2. Check for extra whitespace or newlines:
    Terminal window
    echo "$GEMINI_API_KEY" | cat -A
  3. Regenerate a new key in the provider console and update the environment variable.
  4. Ensure you’re using the correct key for the correct provider.

Key in Config File Not Loading

Error: Provider loads but key seems ignored

Fix:

  • If using ${ENV_VAR} syntax in your config, the variable must be exported in the same shell session.
  • Verify the variable name matches exactly (case-sensitive).
  • For OpenCode, check your opencode.json uses the correct format.

Rate Limiting

429 Too Many Requests

Error: Rate limit exceeded or 429 status code

Fix:

  1. Wait — most rate limits reset after 60 seconds.
  2. Switch providers — move to a provider with higher limits or a free tier you haven’t exhausted:
    • Groq free tier: generous limits
    • Gemini free tier: good for light use
    • DeepSeek: very low cost if you need to pay
  3. Upgrade your plan — paid tiers on most providers have higher rate limits.
  4. Add retry logic — some agents handle retries automatically. Check your agent’s configuration.

Tokens Per Minute (TPM) Limit

Error: Token rate limit exceeded

Fix:

  • Reduce maxTokens in your config: 
    { "maxTokens": 2048 }
  • Break large tasks into smaller requests.
  • Switch to a model with higher TPM limits on your account.

Connection Timeouts

Request Timeout

Error: Connection timed out or ETIMEDOUT

Fix:

  1. Check your internet connection:
    Terminal window
    curl -I https://generativelanguage.googleapis.com
  2. Check if the provider’s API is down — visit the provider’s status page.
  3. Increase timeout settings if your agent supports it:

{ “timeout”: 60000 }

4. **Use a faster model** — switch from a large model (e.g., GPT-4o) to a smaller one (e.g., GPT-4o-mini) for quicker responses.
5. **Proxy/firewall issues** — if you're behind a corporate proxy, ensure API domains are allowed.


### SSL/Certificate Errors


**Error:** `SSL certificate error` or `CERTIFICATE_VERIFY_FAILED`


**Fix:**
1. Update your system's CA certificates:
 ```bash
 sudo apt update && sudo apt install ca-certificates
  1. If behind a proxy, configure your environment to trust the proxy’s certificate.

Common Error Messages

model_not_found

Cause: The model name in your config doesn’t match what the provider expects.

Fix:

  • Check the exact model name in the provider’s documentation.
  • Common mistakes:
    • Using claude-3-sonnet instead of claude-sonnet-4-20250514
    • Using gpt4 instead of gpt-4o
    • Using gemini-pro instead of gemini-2.0-flash

insufficient_quota

Cause: You’ve exceeded your billing quota or free tier credits.

Fix:

  • Check usage in the provider’s dashboard.
  • Add a payment method or upgrade your plan.
  • Switch to a provider with remaining credits.

context_length_exceeded

Cause: Your input exceeds the model’s context window.

Fix:

  • Reduce the size of your input (code files, prompts).
  • Use a model with a larger context window:
    • Gemini: up to 1M tokens
    • Claude: up to 200K tokens
  • Summarize or chunk large inputs before sending.

invalid_request_error

Cause: Malformed request or unsupported parameter.

Fix:

  • Verify your config JSON is valid:
    Terminal window
    cat opencode.json | python3 -m json.tool
  • Check that maxTokens and other parameters are within the model’s supported range.
  • Remove any unsupported fields from your config.

network_error / ECONNREFUSED

Cause: Cannot reach the provider’s API endpoint.

Fix:

  1. Check DNS resolution:
    Terminal window
    nslookup api.openai.com
  2. Test connectivity:
    Terminal window
    curl https://api.openai.com/v1/models
  3. Disable VPN or proxy temporarily to isolate the issue.
  4. Check firewall rules allow outbound HTTPS (port 443).

Still Having Issues?

  • Check the Provider Overview for provider-specific setup guides.
  • Review your agent integration configuration.
  • Consult your provider’s official documentation and status page.