Skip to content
ProxAI

Troubleshooting

Troubleshooting

Section titled “Troubleshooting”

Start from the symptom the client sees, then inspect the narrowest useful layer. Each card gives likely causes, first checks, a useful capture phase, and the docs that own the deeper explanation.

Request shape and routing

Section titled “Request shape and routing”
Client sees 404 or unsupported path
Layer: IngressUseful capture: inbound_request
Likely causes
  • The client is not using a supported endpoint.
  • The client base URL includes an extra `/v1` or misses the expected route suffix.
Next checks
  • Use `/v1/responses`, `/v1/chat/completions`, or `/v1/messages`.
  • Check whether the client wants base URL with or without `/v1`.
  • Confirm the local proxy is listening on the configured port.
Related docs
ProtocolsDefaults
Client sees 400 invalid_request_error
Layer: Ingress validationUseful capture: inbound_request
Likely causes
  • Inbound request body is not valid for the detected protocol.
  • The client sent an unsupported shape for the selected endpoint.
Next checks
  • Check the request path.
  • Capture one sanitized inbound request.
  • Compare payload shape with the protocol guide.
Related docs
Protocol guideError responses
Wrong provider is selected
Layer: RoutingUseful capture: provider_request
Likely causes
  • Route order or model pattern matched an unexpected route.
  • `request_protocol` guard was omitted or mismatched your intent.
  • Default provider fallback handled the request.
Next checks
  • Review `[[routing.routes]]`.
  • Check `routing.default_provider_names`.
  • Compare actual inbound protocol with any explicit `request_protocol` guard.
Related docs
Route matchingRouting
Protocol mismatch configuration error
Layer: Routing / conversionUseful capture: provider_request
Likely causes
  • A route model matched, but explicit `request_protocol` differed from the detected inbound protocol.
  • The selected provider protocol requires an unsupported conversion pair.
Next checks
  • Set `request_protocol` only for endpoint-specific routing.
  • Check supported conversion pairs.
  • Inspect the provider protocol for the selected provider.
Related docs
Route matchingProtocols

Provider and upstream

Section titled “Provider and upstream”
Client sees 401 / 403 upstream
Layer: Provider authenticationUseful capture: provider_request
Likely causes
  • Provider `api_key` is missing, wrong, expired, or scoped incorrectly.
  • The upstream rejects the provider auth header ProxAI sends.
Next checks
  • Check local `[providers.<name>].api_key`.
  • Confirm provider protocol determines auth header shape.
  • Avoid passing real keys through client UI when provider config should own auth.
Related docs
ConfigurationContracts
Client sees 429 upstream
Layer: Upstream statusUseful capture: upstream_response
Likely causes
  • Upstream rate limit or quota exhausted.
  • Concurrency is too high for the selected provider.
Next checks
  • Inspect preserved `Retry-After` and rate-limit headers.
  • Check provider quota.
  • Lower `[server].max_concurrent_requests` if useful.
Related docs
DefaultsError responses
Client sees 502 / 503 / 504 upstream_error
Layer: Upstream transport / statusUseful capture: upstream_response
Likely causes
  • Provider returned a non-2xx status.
  • Upstream error body was empty, non-JSON, or an unknown shape.
  • Network or idle-read timeout occurred.
Next checks
  • Check provider `base_url`.
  • Capture upstream response for one request.
  • Confirm the upstream endpoint is reachable and protocol-compatible.
Related docs
ConfigurationError responses

Streaming

Section titled “Streaming”
Stream starts but never completes
Layer: Streaming semanticsUseful capture: upstream_response
Likely causes
  • The provider did not send the protocol terminal event.
  • The upstream connection is still open but semantically stalled.
Next checks
  • Compare against expected terminal events.
  • Check stream outcome logs.
  • Capture upstream SSE tail.
Related docs
Streaming behaviorStreaming internals
Tool-call arguments stall
Layer: Streaming tool-call semanticsUseful capture: upstream_response
Likely causes
  • Upstream started tool arguments but did not emit the matching done event.
  • Semantic tool-call timeout is too high for the client experience you want.
Next checks
  • Tune `[tool_calls].timeout_secs`.
  • Check provider event sequence.
  • Capture the upstream SSE tail.
Related docs
Streaming behaviorDefaults
Client receives malformed streaming event
Layer: Translation / response reconstructionUseful capture: outbound_response
Likely causes
  • Provider stream shape does not match the selected provider protocol.
  • Streaming translation encountered an unsupported semantic event.
Next checks
  • Check inbound protocol vs provider protocol.
  • Compare supported conversion pairs.
  • Capture outbound response bytes for one sanitized request.
Related docs
ProtocolsProtocol conversion

Configuration, files, and error rendering

Section titled “Configuration, files, and error rendering”
ProxAI fails to start
Layer: Configuration loadingUseful capture: none
Likely causes
  • `config.toml` is missing required sections.
  • Provider entry is missing a required field.
  • A route references an unknown provider.
Next checks
  • Compare against generated `config.example.toml`.
  • Check local app directory.
  • Review route/provider names for typos.
Related docs
ConfigurationEnvironment
Captures are not written
Layer: Local filesystem / capture configUseful capture: none
Likely causes
  • The phase switch is disabled.
  • You enabled a different phase than the one you are inspecting.
  • The app directory is not the one you expected.
Next checks
  • Run `proxai capture status`.
  • Check `[capture]` switches.
  • Confirm app directory location.
Related docs
Capture phasesEnvironment
Client expected JSON but got text
Layer: Error renderingUseful capture: outbound_response
Likely causes
  • `[error_responses].format` is set to `text`, which is the readable default.
  • Client expects OpenAI-style JSON error payloads.
Next checks
  • Set `[error_responses].format = "json"` if the client requires JSON.
  • Check outbound response content type.
Related docs
Error responsesConfiguration
Section titled “Related docs”
ConfigurationRuntime tasks for server, routing, providers, capture, logging, and errors.Route MatchingExact route outcomes and protocol guard behavior.Capture PhasesPhase boundaries and privacy risk.Streaming BehaviorExpected streamed responses and terminal events.