Troubleshooting#

Health returns 503#

Read the health response's missing readiness items. Complete owner bootstrap, configure a serving lane and rebuild if the route manifest is missing or stale. Verify until health returns 200 and ready: true.

Confirm APP_URL exactly matches the browser's HTTPS origin and system time is correct. A passkey enrolled for another domain must be enrolled again; do not weaken origin checks.

A recovery code no longer signs anyone in on its own. Recovery redeems a grant and sets a new credential; there is no recovery-code login route to fall back to.

If a member reports a lockout after someone else's failed attempts, check that the reverse proxy sets the header named by SUGAR_TRUSTED_CLIENT_IP_HEADER. Without a trusted client-address header Sugar cannot separate callers, so it applies only the loosest per-identifier threshold.

API returns 401 or 403#

Use Authorization: Bearer, confirm the key was copied correctly, remains active and belongs to a permitted member. Check quota and role separately from authentication.

An sgr_admin_ automation token is refused admin_token_route_forbidden on routes that are deliberately human-only, including routing-policy authoring and promotion. Use an administrator session for those.

No model is available#

Test provider credentials, sync models and confirm the model is both enabled and exposed. Inspect supply policy and circuit-breaker state. A seeded lane also needs its release qualified and the supply policy revision that admits it.

Every lane is ruled out by the request#

A 503 that names lanes and a reason is about this request, not about capacity. Either a lane does not declare tool support, or its declared context window is smaller than the prompt plus reserved output. Send the request without tools, shorten it, or record the capability finding under Providers → the lane → Capabilities. A lane whose context window was never declared stays eligible for ordinary traffic, but Conduit model hysteresis and the Flex execution tier exclude it — so on a Flex-tier 503 check whether the named lanes are missing a declared window rather than carrying one that is too small. See Routing and failover.

Sync models is refused#

Sync models returns HTTP 409 provider_catalog_seeded on a provider whose public catalogue is not its plan's catalogue, such as Cline Pass. Nothing is wrong: those lanes are seeded by Sugar and are corrected through the model row, not through discovery.

A batch submission is refused#

503 batch_pricing_unset means the model has an enabled batch lane but no batch prices. Batch prices are never seeded or discovered — an administrator sets the batch input and batch output price on the model row in Admin → Providers. 503 batch_lane_unavailable is the different failure: no enabled, exposed OpenAI or Anthropic lane exists for that model. Neither is a transient error, so do not retry until the record is corrected.

Responses requests return 400#

/api/v1/responses refuses a field it cannot honour instead of dropping it. text.verbosity, reasoning.summary, metadata, truncation: "auto" and a non-empty include are named in the error. Remove the field, or move the request to /api/v1/chat/completions.

Streaming stalls#

Test directly against loopback to separate Sugar from the proxy. Confirm the client consumes SSE incrementally and the proxy does not buffer. Preserve the request ID before retrying.

A metrics scrape fails#

401 means no credential or a bearer that is not an admin automation token; 403 admin_token_scope_forbidden means the token lacks usage:read. See Monitoring and metrics.

Stored provider credentials fail after restore#

Confirm the restored service uses the original SUGAR_CREDENTIAL_KEY. Do not rotate it by replacing the environment value; re-enter credentials through the portal only under an intentional rotation plan.

Remove API keys, cookies, prompts, provider error bodies and private endpoint addresses from shared diagnostics.