Troubleshooting failed requests
Narrow Claude Code request failures through safe logs, frogp status, route/default provider checks, auth/OAuth, capability fallbacks, and clean restore.
This guide classifies failed Claude Code requests and recovers them using safe evidence only. Do not copy credentials, OAuth tokens, prompts, request bodies, or account screenshots into issues.
0. Classify the symptom in one line
| Symptom | Check first |
|---|---|
| Claude Code cannot find a provider model | Route/default provider checks below |
| Request immediately fails with 401/403 | Auth/OAuth checks below |
| Request hangs or stream disconnects | Dashboard safe log phase below |
| Only image or web search requests fail | Capability fallback checks below |
| Claude Code must return to native state | Clean restore path below |
1. Check the dashboard safe log phase
Open the dashboard:
frogp guiIn Activity, find the failed request id and check the last phase. The request log is not a secret store; it does not save API keys, OAuth tokens, prompt bodies, or account identities.
| Last phase | Meaning | Action |
|---|---|---|
parse | Claude Messages payload shape did not match what the relay expected. | Check Claude Code version and reproduction conditions; compare whether the same request works against native Claude. |
route | Model id did not resolve to a provider lane. | Check default provider, provider prefix, and disabled model state. |
oauth / auth | Credentials are missing or expired. | Check provider login state and authMode. |
adapter_build | FrogProgsy could not build the provider request. | Check adapter id, baseUrl, and model option gates. |
upstream_connect | Provider HTTP/SSE connection failed. | Check baseUrl, network, provider status, and endpoint path. |
stream_bridge | Provider output failed while converting back to Claude Messages. | Check whether the provider changed tool, reasoning, or stream shape. |
finalize | Response finished and cleanup/logging is running. | Check usage/log write permissions and local disk state. |
If the safe error summary is not enough, report only route, provider, adapter, phase, status code, and request id.
2. Check route/default provider
First confirm the relay is running:
frogp status- If it is not running, start it with
frogp startor from the dashboard. frogp statusis PID-based. For port mismatches, check~/.frogprogsy/config.jsonand the endpoint injected into Claude Code settings.- If request health is unclear, compare dashboard status with the latest safe proxy log error.
Then check the provider route:
- In dashboard Providers, confirm
defaultProviderpoints to a provider that exists. - If Claude Code selected
provider/model, theproviderprefix must match a key underprovidersinconfig.json. - In dashboard Models, confirm the routed model is not disabled.
subagentModelschanges exposure order only; it does not create routes.- If a provider's live
/modelscall is unreliable, pin it withliveModels: falseand amodelsallowlist.
For a stale Claude Code model picker, refresh the Claude Code catalog for the active profile:
frogp claude reload-models <profile-id>Then start a new Claude Code session or resume so /v1/models is fetched again. Already-open /model screens do not hot reload. If the proxy is not answering, run frogp refresh first, then reload the profile catalog.
Repair a retired model
Read the live report first, save an exact ordinary-route fallback only when you want automatic handling, or permanently replace the affected reference:
frogp models continuity
frogp models continuity set <provider/model> --fallback <provider/model> --auto retired
frogp models continuity replace <reference-id> <provider/model>Copy <reference-id> from the report; it prevents a stale report from changing the wrong setting. set preserves the configured owner and only saves the exact request-time alternative. replace changes the stored owner after validation. The dashboard Models page offers the same problem-first actions.
3. Check Auth/OAuth
Split 401/403 and login loops by provider type.
| Provider type | Check | Recovery |
|---|---|---|
| API-key provider | Whether apiKey is a literal or ${ENV_VAR} reference, and whether the shell/runtime environment has that env value. | Save the provider again in the dashboard or fix the env reference in config.json. |
| OAuth provider | Dashboard OAuth status and whether ~/.frogprogsy/auth.json has a provider token. | Run frogp login <provider> again. |
| Forward auth provider | Whether Claude Code sent an allowlisted upstream-compatible auth header. | Check native Claude/ChatGPT/Codex login state and restart the relay. |
| Local provider | Whether the keyless endpoint is actually running. | Start Ollama/vLLM/LM Studio first and match baseUrl. |
Never share OAuth credentials manually or paste them into logs. Issues should contain provider name, auth mode, status code, and last safe phase only.
4. Check capability fallbacks
Web search and image requests may require capability fallbacks when the main provider cannot handle them directly.
Web search
- Confirm
webSearchFallback.enabledistrue. - The capability fallback model must be able to use an OpenAI Responses forward/key provider.
- If
maxSearchesPerTurnis too low, the search loop may stop early. - If
timeoutMsis too low, upstream search may fail mid-turn.
Image fallback
- For a text-only target model, confirm
imageFallback.enabledistrue. - If
modelCapabilities.<model>.inputis text-only, images are converted to text descriptions before the main call whenimageFallbackis enabled. - The capability fallback
modelmust support vision. - Base64 images must not leak into prompt text. Safe logs do not store image bodies.
If capability fallbacks are unstable, reproduce with a search/vision-native main route to separate capability fallback failure from main provider failure.
5. Clean restore path
Use the narrowest command that returns Claude Code to the state you need.
| Purpose | Command | Preserves |
|---|---|---|
| Restore Claude Code settings/catalog only | frogp restore | Running proxy, FrogProgsy config/auth |
| Stop proxy too | frogp stop | FrogProgsy config/auth |
| Remove FrogProgsy-managed traces | frogp uninstall | Other Claude Code user state |
frogp restore and frogp stop remove only FrogProgsy-owned Claude Code settings and catalog entries. They do not remap Claude Code history; frogp recover-history --legacy-openai is a retired no-op.
6. Record safe reproduction details
Useful issue/PR details:
- OS and FrogProgsy version
- Non-secret
frogp statussummary - Failed request id and dashboard safe phase/status
- Provider key name, adapter id, auth mode, and routed model id
- Whether
webSearchFallbackorimageFallbackwas used - Whether the issue reproduces after clean restore
Do not include:
- API keys, OAuth tokens, or session cookies
- Full prompt or request body
- Account email or organization id
- Provider dashboard screenshots that expose credentials or account details
Dashboard & Activity
The local FrogProgsy control room for provider setup, model visibility, classifier routing, capability fallback choices, safe request activity, usage accounting, and shutdown.
CLI Commands
Complete frogp command contract: setup, relay lifecycle, provider login, refresh, models, dashboard, recovery, update, and help.