Debugging Workflow

Use this workflow when a client request fails, routes to the wrong provider, returns an unexpected shape, or stalls while streaming.

Workflow

1Read the client errorKeep the HTTP status, payload type, and whether this happened before or during streaming.
2Classify the layerSeparate client request, routing, provider auth, upstream status, translation, and streaming semantics.
3Check logsUse structured logs and request hints before enabling captures.
4Capture one phasePick the narrowest capture phase that answers the question.
5Compare expected vs actualCompare inbound request, provider request, upstream response, or outbound response.
6Disable and sanitizeTurn capture off and sanitize artifacts before sharing anything.

Symptom	Likely layer	Useful phase
Client request rejected immediately	Inbound request validation	`inbound_request`
Wrong provider selected	Routing / config	`inbound_request` and logs
401 / 403 from upstream	Provider auth	`provider_request` plus upstream status
Provider returns unexpected JSON	Upstream response shape	`upstream_response`
Client receives wrong protocol shape	Translation / outbound reconstruction	`outbound_response`
Stream stalls after tool arguments	Streaming semantics	stream logs and tool-call timeout

proxai capture enable provider-request
# reproduce once
proxai capture disable provider-request

See Capture Phases for phase names and privacy risk.

Include the ProxAI version and OS.
Include the inbound endpoint and model name.
Include the selected provider protocol, not the provider API key.
Prefer sanitized captures or minimal synthetic payloads.
Never include Authorization, api_key, private prompts, private outputs, or full upstream URLs containing secrets.