> ## Documentation Index
> Fetch the complete documentation index at: https://oximy.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Relay

> Diagnose authentication, provider, routing, OTEL, reporting, budget, and traffic-correlation problems.

Start with the failing boundary: authentication to Relay, model decision, provider execution, telemetry export, or report generation.

<AccordionGroup>
  <Accordion title="Relay rejects the key" icon="key" defaultOpen>
    Confirm the value begins with `ox_`, belongs to the intended project, is not disabled or revoked, and has not expired. The full key is shown only at creation; a displayed prefix is not usable authentication.
  </Accordion>

  <Accordion title="No models are callable" icon="boxes">
    Add a provider credential to the project, enable it, and run verification. Check the provider-specific error and any custom API base URL. A catalog model can exist without being callable for this project.
  </Accordion>

  <Accordion title="A model is callable but cannot be a routing candidate" icon="route">
    Callable and routable are separate properties. Automatic and custom routers require routing-engine support. Use a routable candidate or request the callable model directly.
  </Accordion>

  <Accordion title="Automatic routing does not select a model" icon="sliders-horizontal">
    Confirm the request uses `oximy/auto`, the routing mode is automatic, at least one candidate is callable and routable, and a fallback is configured. Inspect the Traffic routing reason and upstream error.
  </Accordion>

  <Accordion title="The fallback did not save a route-only request" icon="signpost">
    Route-only returns a decision but does not execute the provider call. Your application owns the decision-service timeout, provider retry, and final application fallback.
  </Accordion>

  <Accordion title="OTEL traffic is missing" icon="activity">
    Check the ingest URL, `/v1/traces` path for standard OTLP/HTTP, `Authorization: Bearer ox_...` header, exporter protocol, and project key. Generate one identifiable trace and first verify arrival before debugging missing attributes.
  </Accordion>

  <Accordion title="Traffic arrived but fields are empty" icon="list-tree">
    Inspect the raw trace spans and instrumentation attributes. Model, token, cost, latency, task, and decision fields can only be displayed when the gateway or telemetry supplies them.
  </Accordion>

  <Accordion title="Agent-run grouping looks wrong" icon="workflow">
    Current grouping infers continuity from message prefixes over a bounded recent window. Treat it as a navigation aid and inspect the ordered traffic rows when exact session boundaries matter.
  </Accordion>

  <Accordion title="Shadow or eval work is not running" icon="flask-conical">
    Verify a callable provider, candidate model, enabled setting, sample availability, and remaining budget. Shadow and evaluations execute additional calls and can stop at their configured cap.
  </Accordion>

  <Accordion title="A report has unroutable samples" icon="chart-line">
    Historical requests may not match the current candidate capabilities or contain enough decision context. Narrow the traffic cohort, review signal filters, and inspect representative unroutable rows.
  </Accordion>

  <Accordion title="A key cannot be created" icon="credit-card">
    Check plan entitlements, payment requirements, key-group policy, and project state. Durable key creation can require Relay billing coverage or a payment method.
  </Accordion>
</AccordionGroup>

## Collect before escalating

Include:

* project ID and Relay key prefix, never the full secret
* UTC timestamp and request or decision identifier
* integration path: gateway, existing gateway, OTEL, or route-only
* requested and resolved model
* provider verification status
* HTTP status and sanitized error
* relevant limit and budget state

<Warning>
  Do not paste provider credentials, full Relay keys, prompts containing sensitive data, or unsanitized provider responses into a support ticket.
</Warning>