# Troubleshooting

Never echo a provider key, pairing code, or agent token while debugging.

## Pairing

| What you see | What to do |
|---|---|
| A terminal is required | Run the CLI in an interactive macOS or Linux terminal. Do not pass the secret as an argument or pipe it through chat. |
| Invalid or expired pairing code | Create a new code at `/agent`. Codes expire after 10 minutes. |
| Pairing code already used | Create a new code. Never retry the same exchange. |
| Agent session expired | Run `login` again. Sessions expire after eight hours. |
| Not paired | Run `login`; do not manufacture or edit the session file. |

## Probe

| What you see | What to do |
|---|---|
| Provider terms confirmation required | Stop until the user reviews their provider terms. Then rerun with `--confirm-provider-terms`. |
| Provider is unavailable until a date | The CLI stopped before asking for a key. Offer the named alternative provider; do not retry this one before that date. |
| Provider is served per account | Ask the user for their account identifier and rerun with `--account <identifier>`. Do not guess it. |
| 504 / Surplus took too long | Retry the `sell` command once. If it repeats, stop and report the timeout. |
| Host rejected the key (401/403) | Stop. The key is inactive, truncated, or from the wrong account. Do not guess. |
| Surplus does not support the host | The key was not checked. Use a catalog provider or an already-supported custom URL. |
| No attainable text models recommended | Review demand with the user or name discovered models explicitly with `--models`. Do not invent IDs. |

## Listing

| What you see | What to do |
|---|---|
| 429 / `retryAfterSec` | The CLI waits and retries that model once. If it still fails, report it and stop retrying. |
| `already_listed` | Treat the model as skipped. The agent token cannot delete or relist it. |
| 502 / 503 / 504 | The CLI retries once. Keep successful rows and report the rest. |
| `owner_policy_queue_full` | The settings queue is full, so the CLI stopped and marked the remaining models failed without sending them. Wait at least five minutes, then retry only the failed models if the user asks. |
| Mixed created and failed rows | Do not rerun the whole batch. Retry only a failed model if the user asks. |

## Status

| Label | Meaning | Action |
|---|---|---|
| live | Healthy and on the book | None |
| cooling | Temporary quiet | None |
| backing off | Surplus marked it unhealthy | Wait; use the browser to replace a revoked or exhausted key. |
| paused | Daily cap reached or leftover hours are off | Wait or use the browser dashboard. |
| syncing | House book has not settled | Check `status` later. |

## Support

gm@galleonlabs.io. Do not invent providers, model IDs, routes, or environment values.

## Revoked or unregistered session

If access was revoked or the session predates owner controls, pair again at https://tokensto.cash/agent. Do not bypass registry checks or repeatedly retry the old token. A 503 access-check failure is temporary: retry later without creating another session.

## Listing plan changed

No listings were created. Show the newly returned plan and obtain approval for its current `planId`; do not silently approve the new hash.
