/troubleshooting

Troubleshooting

Fix common issues with free-claude-code. Connection errors, authentication, model mapping, and provider-specific problems.

Troubleshooting

Fix common issues with free-claude-code. Work through these steps in order.

Proxy won’t start

Port already in use

ERROR: Address already in use

Change the port:

uv run uvicorn server:app --host 0.0.0.0 --port 8083

Then update your Claude Code environment:

ANTHROPIC_BASE_URL="http://localhost:8083"

uv not found

Install uv:

pip install uv

Or update it:

uv self update

Missing dependencies

uv sync

Claude Code still asks for Anthropic login

Check the base URL

Verify ANTHROPIC_BASE_URL points to the proxy root, not /v1:

# Correct
ANTHROPIC_BASE_URL="http://localhost:8082"

# Wrong
ANTHROPIC_BASE_URL="http://localhost:8082/v1"

OAuth flow is normal

The first time you use Claude Code, it may ask you to authorize via Anthropic’s OAuth. Complete this once. After authorization, the proxy handles all API calls.

Extension needs reload

If using VSCode or IntelliJ, reload the extension after changing environment variables.

”Invalid API key” errors

NVIDIA NIM

  • Verify key starts with nvapi-
  • Generate a new key at build.nvidia.com
  • Check the key hasn’t expired

OpenRouter

  • Verify key starts with sk-or-
  • Check you have credits (for paid models)
  • Free models need :free suffix: open_router/model:free

DeepSeek

”Model not found” errors

Check provider prefix

Valid prefixes: nvidia_nim/, open_router/, deepseek/, lmstudio/, llamacpp/

# Correct
MODEL="nvidia_nim/z-ai/glm4.7"

# Wrong
MODEL="nvidia/z-ai/glm4.7"

Verify model exists

Case sensitivity

Organization and model names are case-sensitive:

# Correct
MODEL="nvidia_nim/moonshotai/kimi-k2.5"

# Wrong
MODEL="nvidia_nim/MoonshotAI/Kimi-K2.5"

Rate limit errors (429)

NVIDIA NIM free tier

You are hitting the 40 req/min limit. The proxy automatically retries with exponential backoff. To reduce rate limit pressure:

PROVIDER_RATE_LIMIT=35
PROVIDER_MAX_CONCURRENCY=2

OpenRouter free tier

Free tier limits vary by model. Switch to a different free model or add credits.

Local providers

LM Studio and llama.cpp have no rate limits. If you hit limits, you are likely using a remote provider—check your configuration.

Connection refused errors

Local provider not running

LM Studio or llama.cpp server must be running before you start the proxy:

# LM Studio: Start server in Developer tab
# llama.cpp:
llama-server -m model.gguf --port 8080

Wrong port

Verify LM_STUDIO_BASE_URL or LLAMACPP_BASE_URL matches your actual server port.

Firewall blocking

Ensure localhost connections are allowed. Check firewall rules for ports 8082, 1234, 8080.

Slow responses

CPU inference

Local models on CPU are 10-50x slower than GPU. Solutions:

  • Enable GPU with -ngl 999 (llama.cpp) or LM Studio GPU settings
  • Use smaller models (4B instead of 35B)
  • Switch to NVIDIA NIM for fast cloud inference

Rate limit backoff

If you see repeated 429 errors, the proxy is waiting to retry. Reduce request frequency or use a provider with higher limits.

Large context

Long conversations take more time to process. Start a new session with /clear (Discord/Telegram) or restart Claude Code.

Discord bot not responding

Check bot token

Reset the token in Discord Developer Portal if unsure.

Enable Message Content Intent

In the Developer Portal → Bot → Privileged Gateway Intents, enable “Message Content Intent”.

Check channel IDs

Verify ALLOWED_DISCORD_CHANNELS contains the correct channel IDs. Use “Copy Channel ID” in Discord (requires Developer Mode enabled).

Wrong messaging platform

Ensure MESSAGING_PLATFORM="discord", not telegram.

Telegram bot not responding

Check bot token

Get a fresh token from @BotFather with /token.

Verify user ID

Check your user ID with @userinfobot. Ensure ALLOWED_TELEGRAM_USER_ID matches.

Bot privacy mode

If using the bot in a group, disable privacy mode in BotFather:

  1. Message @BotFather
  2. Send /mybots
  3. Select your bot
  4. Bot Settings → Group Privacy → Turn off

Voice notes failing

Check extras installed

uv sync --extra voice_local     # For local Whisper
uv sync --extra voice           # For NVIDIA NIM voice

Check configuration

VOICE_NOTE_ENABLED=true
WHISPER_DEVICE="cpu"    # or "cuda" or "nvidia_nim"

Out of memory (local Whisper)

Use a smaller model:

WHISPER_MODEL="tiny"    # Instead of "large-v3"

Or use CPU instead of GPU:

WHISPER_DEVICE="cpu"

Getting help

If these steps don’t resolve your issue:

  1. Check the GitHub Issues for similar problems
  2. Enable debug logging: 
    uv run uvicorn server:app --host 0.0.0.0 --port 8082 --log-level debug
  3. Include these details in a bug report:
    • free-claude-code version
    • Python version (python --version)
    • uv version (uv --version)
    • Claude Code version (claude --version)
    • Full error message
    • Steps to reproduce