Troubleshooting

Common issues and solutions

Troubleshooting

Common issues and solutions.

Known Limitations

These are expected behaviors, not bugs. See Introduction for the full list.

Issue	Expected?	Solution
Cold start delay (10-20s)	Yes	First request after idle is slow. Subsequent requests are fast.
529 quota errors	Yes	Auto-retry usually fixes it. If persistent, wait 30-60 seconds.
Web search not working	Yes	Google grounding protocol differs. Use without web search.
High latency (South America, etc.)	Yes	Server is in Singapore. Farther = slower.

---

Connection Issues

Connection refused or Failed to connect

Cause: Cannot reach the proxy server.

Solutions:

1. Check your internet connection
2. Test the endpoint:
   curl YOUR_ENDPOINT_URL/health
   
3. If that fails, try again in a few minutes

Timeout errors

Cause: Request taking too long.

Solutions:

1. Try once again — could be cold start
2. If first request, wait 10-20 seconds (cold start is normal)
3. Check your internet speed

Cold start delay

Cause: First request after idle spins up the backend.

Solutions:

1. This is normal — wait 10-20 seconds
2. Subsequent requests will be fast
3. If every request is slow, check your internet connection

---

Authentication Issues

Invalid API key

Cause: API key not recognized.

Solutions:

1. Double-check your API key for typos
2. Ensure no extra spaces before/after the key
3. Contact admin on Discord: presumptiousbastard

401 Unauthorized

Cause: Authentication failed.

Solutions:

1. Verify your API key is correct
2. Check the Base URL format:
   • Claude Code: YOUR_ENDPOINT_URL
   • Cursor: YOUR_ENDPOINT_URL/v1
   • Cline/Roo: YOUR_ENDPOINT_URL (no /v1)
3. Contact admin if key was recently created

---

Quota & Rate Limit Issues

529 Resource Exhausted

Cause: Temporary quota limit hit.

Solutions:

1. Simply retry — auto-retry usually works
2. If persistent, wait 30-60 seconds
3. Switch to gemini-3-flash temporarily to preserve Claude quota

Rate limited or Quota exceeded

Cause: Heavy usage in short time.

Solutions:

1. Wait a few minutes
2. Use gemini-3-flash for simple tasks
3. If you consistently hit limits, contact admin about usage patterns

---

Model Issues

Model not found

Cause: Invalid model name.

Solutions:

1. Use exact model names:
   • claude-opus-4-5-thinking
   • claude-sonnet-4-5-thinking
   • claude-sonnet-4-5
   • gemini-3-flash
2. See Available Models for full list

Extended thinking not working

Cause: Using model without -thinking suffix.

Solutions:

1. Use claude-opus-4-5-thinking or claude-sonnet-4-5-thinking
2. Models without -thinking don’t use extended thinking mode

---

Tool-Specific Issues

Claude Code: command not found

Install Claude Code first:

npm install -g @anthropic-ai/claude-code

Claude Code: Login prompt appears

Your config isn’t loading. Check:

1. ~/.claude-proxy/settings.json exists
2. You’re using claude-proxy alias (not just claude)
3. Run source ~/.zshrc to reload

Cline: Settings not saving

1. Close VS Code completely
2. Reopen and reconfigure
3. Check VS Code has write permissions

Cursor: Model not appearing

1. Restart Cursor after adding model
2. Check model is toggled “on” in settings
3. Try removing and re-adding the model

OpenCode: Images not working

Add modalities config to your opencode.json:

{
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "YOUR_ENDPOINT_URL"
      }
    }
  },
  "modalities": ["text", "image"]
}

---

Still Stuck?

DM on Discord: presumptiousbastard — happy to help with setup or issues.