Skip to Content

Subscription troubleshooting

Start with the relay ID, subscription ID, request ID, native client version and observed error/outcome. Redact the relay key, access/refresh tokens and native authentication files before sharing diagnostics.

The import or sign-in is not ready

  • Complete pending browser/device-code steps before creating a relay.
  • Import a subscription login, not a provider API key.
  • For an existing account, choose Update existing to retain the selected entry’s relay memberships. --force means Add another.
  • A cached access-token expiry does not prove the login is unusable: Modem may renew it. A definitively rejected or uncertain rotating refresh requires reconnection; repeatedly importing the same stale material is not a recovery.
  • If renewal rotated credentials, the original native CLI may need to sign in again.

Do not paste credential JSON into a bug report to prove the account is signed in.

Check the primary subscription first. A signed-out primary makes the whole relay signed out. Reconnect/update it or change membership deliberately. An available secondary is not automatically promoted for essential account metadata.

If a native client still uses its own login, apply the link’s generated setup in its launch shell and restart it. Check for stale auth/routing overrides; Grok and Claude setup uses separate client homes for this reason. Do not replace the relay key with an admin or provider API key.

A model or quota is unavailable

Check the provider/account’s observed model catalog and the timestamp. A catalog union can be partial when secondary observations fail, and the primary catalog must be usable. A displayed model can depend on a single member.

An unavailable quota is not a zero balance. A visible balance is not a capacity reservation. Check the model/surface-specific window, short/weekly resets and credit permission for this membership. The provider may refuse between observation and dispatch.

If a compatible member lacks quota, that is a quota failure, not proof that the requested feature is unsupported. If no member can preserve the model/tool/thinking requirements, changing order cannot resolve the incompatibility.

Retry only when the outcome is known

The relay distinguishes:

SituationBehavior
Explicit qualifying refusal before generationTry an eligible next member within the configured account/fallback-attempt cap
Grok/Claude definitive pre-generation HTTP 401 with a concurrently replaced credentialA separate bounded same-identity recovery may send the changed credential; the current Codex dispatcher has no equivalent path
Network interruption or unknown provider acceptanceDo not replay automatically
Output/positive usage or a stream already handed to the clientNo transparent account-switch retry

Codex/Grok quota fallback requires a confirmed exhausted-quota refusal without output or positive usage. A bounded initial stream inspection can identify such a refusal before handing the stream to the client. Claude additionally recognizes a native pre-generation admission refusal; it does not report that refusal as verified quota exhaustion unless the quota classifier establishes it. A short account/model admission cooldown prevents immediately hammering the same refusal.

The selected default allows three account/fallback attempts including the initial selection. Grok/Claude’s authentication recovery has a separate default budget of one additional send per logical request; it requires a changed credential for the same identity and does not consume another fallback slot. Every actual send is still recorded as an upstream attempt, so the network-send count can exceed three. Server policies configure these budgets independently. A request that fails a Modem product limit or has an uncertain upstream outcome must not be blindly retried to seek another subscription.

Inspect Usage for the logical request and its separate upstream attempts. Unknown terminal usage and interrupted outcomes should remain unknown, not be rewritten as zero consumption. A successful direct account read, or a later successful request, does not explain an earlier failed attempt.

Distinguish account inspection from a diagnostic chat

modem-cli subscription-signins account --sign-in-id '<subscription-id>'

This reads a recent account/usage observation and can renew stored authentication. It does not send a generation request or test a relay link.

A diagnostic chat does run a native coding agent on the server:

modem-cli subscription-signins chat \ --sign-in-id '<subscription-id>' \ --prompt 'Reply briefly with hello.'

It sends one native turn using the saved subscription and may consume provider allowance. It has a four-minute deadline and requires the selected native executable on the Modem server: Codex app-server, Grok ACP or Claude Agent SDK. The server creates a temporary home/workspace, passes access credentials rather than refresh credentials, and cleans up the owned execution afterward. Claude selects Haiku with tools disabled and a one-turn limit. This diagnostic is disabled in subscription-emulator mode.

A successful diagnostic chat establishes direct server/native execution. It does not verify the relay key, link routing, multiplexing, product limits or relay accounting. Test those with an actual configured relay client and inspect its Usage result.

Last updated on