Skip to content

Troubleshooting

Dhanush edited this page Oct 23, 2026 · 1 revision

Troubleshooting

Start by checking the provider's coverage status, the enabled Cargo feature, and the credential type. The crate returns typed AgentStatError values without remote response bodies or credential values.

Error or symptom Likely cause What to try
FeatureDisabled Provider feature was not built Enable the provider's Cargo feature and rebuild.
Unsupported Provider is planned or outside scope Check Provider Coverage; a feature ID alone is not an adapter.
InvalidCredentials Missing or incompatible credential variant Check whether the adapter needs a bearer token, API key, cookie, or local probe.
Authentication Expired or rejected credential Renew it using the provider's own login flow, then retry. agentstat does not refresh tokens.
PermissionDenied Credential lacks access to the selected account or report Confirm account, organization, and key permissions with the provider.
RateLimited Provider throttled the request Respect the reported Retry-After time when present. The library does not retry automatically.
InvalidResponse Provider's response no longer matches the adapter, or required data is missing Compare with the provider's usage page; report a sanitized schema change.
Configuration Invalid or missing account routing Supply the required workspace or organization ID and check its format.
LocalAccessDisabled Runtime opt-in is missing Call allow_local_files(true) or allow_local_probes(true) as appropriate.
LocalRead Credential file is absent, unreadable, or stored elsewhere Check the supported native path or pass a token explicitly.
UnsupportedPlatform A local probe is not supported on this OS Use a direct HTTPS adapter where available. Local probes are Unix-only.
Transport, Timeout, ResponseTooLarge, or Http Network, deadline, response-size, or HTTP failure Check connectivity and provider status; do not assume the response was valid usage data.

Common OpenCode problems

  • OPENCODE_COOKIE not set: an ignored live test or real_usage -- opencode needs a full Console Cookie header in the same terminal. See OpenCode Go and Zen.
  • Multiple workspaces: set OPENCODE_WORKSPACE_ID to the intended wrk_… or org_… ID. Automatic selection only works with exactly one workspace.
  • Wrong account type: the Zen pay-as-you-go spend path and Go subscription quota path return different fields. A Go API key cannot read the Zen prepaid wallet.
  • Valid API key, missing subscription quota: ordinary inference or other account keys may not have access to the quota endpoint. Check the provider-specific credential path.

Validate a real account

Run the appropriate repository example, compare its result with the provider's own usage page, and note which fields match. The regular tests use synthetic fixtures; a green CI run does not prove a particular account's endpoint still works.

If the problem persists, open an issue with a minimal, sanitized reproduction.

Clone this wiki locally