annon
Start · What can go wrong

What can go wrong, and what to do

Each section says what happens and what you do. The codes in backticks are the ones the SDK, the CLI (with --json) and the MCP server return. When a result carries retryAfterSeconds, wait at least that long before you try again.

Three rules cover most cases:

  • Never pay a second time for the same purchase. Resume the existing purchase with status and open. A saved live or accepted purchase blocks another buy with purchase_open. Only an explicit --force (MCP force: true) creates another purchase despite that saved purchase.
  • Keep your purchase ID and your backup secret. They let you check, resume and open a purchase. Losing them does not lose the file: the same wallet can recover it.
  • Exit code 4 means wait. The CLI exits with it, and CLI JSON and MCP errors carry it as exitCode, for anything still pending or uncertain. It is not proof that the payment failed.

Exit codes: 1 other failure, 2 invalid input or configuration, 3 human approval or contract trust needed, 4 pending or uncertain.

Setup

These errors report invalid input or missing configuration. All exit with code 2.

  • credentials_required: no wallet is selected, or its key is missing. A person signs in with annon login --wallet near (or --wallet evm) and approves each payment in the browser. For an agent, the owner runs annon init --agent once with a key reference, a recovery identity that matches the key and a daily budget, as in agents.md.
  • signer_required: annon init --agent got no key reference or more than one, or a remote signer without exactly one credential reference. The owner runs it again with exactly one of --evm-key-file, --near-key-file, --solana-key-file, --key-env, --keychain-entry, --new-key or --signer (annon --help lists them). In a browser shop it means no wallet is connected: connect one and try again.
  • invalid_arguments: a command, option or value is not valid. Check the command with annon --help or CLI.md; for MCP, check the tool's input schema.

Before you pay

The quote or the purchase expired

  • 1Click: after review and recovery proof, at least ten minutes must remain before the deposit cutoff, or the command returns quote_expired. Do not fund that quote. After confirming that no deposit was sent, request a fresh quote with buy --force using the same URL and source options (MCP force: true). Keep the old purchase record.
  • Base: the SDK signs a payment authorization lasting at most 180 seconds. Keep the saved purchase and check status. Start another purchase only after final chain evidence establishes that the authorization expired or was cancelled without payment. A payment that settled before its deadline can still be unlocked later.
  • NEAR: a purchase is valid for one hour after it is prepared. The SDK pays right away, so this only matters if you pay by hand. A payment that arrives after expiry is not accepted and is refunded in full to your NEAR Intents account (below).

Do not use a local deadline or an uncertain response as evidence that payment failed. Check the saved purchase before starting another one.

The file has no Base route

route_unavailable (exit code 2, "This file does not support the selected payment route."): the file's final on-chain terms have no Base payee, so it cannot be paid directly on Base. Files from NEAR and Solana sellers are like this. You get this before any wallet or payment step, and the host refuses such a payment too. Use near, or 1click with Base as the source chain (annon buy URL --route 1click --from-chain base, or an MCP origin the owner configured for Base). An EVM wallet without --route gets origin_required for such a file, with the same advice.

1Click refuses the quote

1Click can refuse a quote because of its route minimum or available liquidity. When supplied, minimumAmountUsdc gives the reported minimum. Do not send a deposit without a valid quote. Use another available payment route if the file's price cannot be quoted. The demo file costs 0.10 USDC, below the 1Click minimum from Base when we checked, so from Base buy it with near or base.

A refused quote still leaves a saved purchase, so until it expires (within an hour) the next buy of the same file stops with purchase_open, although no payment was sent. When there was no deposit address, no deposit can have been sent: buy with another route and --force (MCP: force: true).

The relayer refuses or is busy

  • not_sponsored: the relayer does not sponsor the Base unlock for this file. You get this before your wallet signs the payment. Pay on NEAR or through 1Click instead.
  • relayer_unavailable or relayer_rate_limited: the relayer is busy or paused. Wait for retryAfterSeconds and try again.
  • budget while selling: the relayer has paused new listings, or a daily sponsorship limit is used up. Buying keeps working. Wait for retryAfterSeconds, or list with your own NEAR account.

If you have already paid, a busy relayer delays the unlock but never cancels your purchase. See the payment is still pending.

You have no NEAR for gas

You need NEAR only on the NEAR route. Other routes:

  • Base: only USDC on Base. You sign an authorization; you need no ETH and no NEAR.
  • 1Click: a supported source asset and enough funds for the quoted deposit and source-chain transaction costs.

NEAR accounts also pay a little storage to sell or recover. See NEAR accounts.

The wallet is on the wrong network

wrong_chain ("Select Base in the wallet."): the SDK asks the wallet to switch to Base. If the wallet cannot, switch it yourself and try again. The payment was not signed.

smart_wallet_unsupported: the Base route needs an ordinary wallet account (an EOA), not a smart contract wallet. Use another account or another route. insufficient_balance means there is not enough USDC on Base: send at least the price in USDC on Base to the paying address (for an agent, the identity annon init --agent printed). The Base route needs no ETH. The refused attempt may still count against the daily budget until its window ends.

The file is moderated or taken down

A seller can name a moderator who can stop new key releases for that file. Before buying a moderated file you must accept that moderator explicitly (unknown_moderator; pass --moderator account.near on buy once you trust it). If the file is already taken down, buy stops with taken_down before you pay, and the file host answers 410.

While you pay

The payment is still pending

settlement_pending (exit code 4) means the payment or the key release is not final yet. Keep the saved purchase.

  • Base: a Base payment must reach Safe finality before NEAR can verify it. Poll status and honor retryAfterSeconds.
  • 1Click: a swap can take several minutes, and its SUCCESS status alone does not prove Annon accepted the purchase.
  • Relayer busy: the unlock is queued and retried. It is delayed, not cancelled.

What you do: wait for retryAfterSeconds (30 seconds when nothing more precise is known), then run annon status 0xPURCHASE_ID again. The MCP server refuses to retry before that time. transaction_uncertain (also exit code 4) means a transaction may have been sent and its result is not confirmed: a reply was lost, or a browser wallet did not report back after its send was called. It includes txHash and purchaseId when they are known; a hash is never invented. annon buy can also return state: "uncertain" with exit code 4, and annon status then reports submission: "uncertain" until the purchase is accepted. Keep that evidence and check the existing purchase or transaction. Do not pay again to resolve uncertainty.

You closed the tab or the program crashed

The purchase is saved, encrypted, before payment authorization or submission. A separate wallet signature may be requested first to prove recovery ownership.

  • Browser: return to the same page in the same browser and resume the saved purchase. lease_busy means another tab holds it. An active tab can renew its hold; after it stops renewing, the hold expires within two minutes. Clearing site data deletes the local record. Export receipts for a separate copy, or recover accepted purchases with the same wallet.
  • CLI or MCP: run annon status 0xPURCHASE_ID. The ID appears in buy output and encrypted backups under stateDir/backups. If you lost it, run annon recover --recovery kind:id with the same configured wallet, replacing kind:id with its identity. Recovery reports successful grants and per-purchase errors. Remove leftover .tmp files and .annon-spool-* directories beside the output before opening again.

While you sell

The shop refuses the upload

A shop sets its own hosting and sponsorship limits (shops and limits). rate_limited means the host's daily upload count for your wallet, your IP address or the whole shop is used up: wait retryAfterSeconds. limited means a relayer admission limit is reached, such as an hourly request limit or a daily sponsorship quota: wait retryAfterSeconds, then resume the saved sale. Do not start a new listing to bypass the limit. host_capacity means the host has no room or does not accept uploads from you; try later or host the file yourself. too_large means the file is above the shop's size limit. A refusal before you sign anything costs nothing. A shop that publishes rules shows them in annon shops and in the annon share result.

The sale stopped part way

Resume the saved sale with the same file (annon share FILE --resume 0xFILE_ID --shop SHOP_ID, or annon sell FILE --resume 0xFILE_ID for a self-hosted sale); never start a new one for the same file. Resume checks the chain before it repeats any step, so an uncertain transaction is never sent twice blindly. Keep the backup secret: without it the saved sale cannot be resumed.

An unfinished verified upload is kept for 24 hours from body verification. After that, requests return upload_expired. The host permits restaging unfinished uploads, but this does not guarantee that every saved CLI checkpoint can resume automatically. Keep the original file and saved seller state; if resumption cannot finish, serve the same registered ciphertext from another host. A file that was published and later expired cannot be republished on that host under the same file ID.

not_sponsored when you register with an EVM or Solana wallet means the relayer does not sponsor this registration. defdone's relayer sponsors files its shop hosts (hosted selling) and the sellers it lists. Use hosted selling, run your own relayer, or sell from a NEAR account.

If the amount was wrong

The SDK always pays the exact price, on every route. These cases come from manual transfers or other software.

You paid less than the price

An underpayment never opens the file.

  • NEAR or 1Click: a valid payment below the price is refunded in full to your NEAR Intents account. The purchase is not used up, so you can pay it correctly or start a new one. See refunds for how to withdraw.
  • Base: your wallet signs for exactly the price, and the file host refuses any other amount before it settles anything.

You paid more than the price

  • NEAR: the purchase is accepted and the excess is refunded to your NEAR Intents account.
  • 1Click: the quote requests delivery of the exact file price. Source-deposit refunds follow 1Click's quote and refund rules, including any refund fee. Check the saved swap status before sending more funds or starting another purchase.
  • Base: your wallet signs for exactly the price.

On Base, always pay through an Annon client. A plain USDC transfer to a file's Base address is not a purchase: it opens nothing, it goes to the seller's recipients, and Annon cannot send it back. Contact the seller.

The 1Click deposit was too small or too late

Send exactly the amount in the instructions, include the memo if there is one, and make sure the deposit is confirmed before depositBefore. Do not deposit after it, even if the address still accepts transfers.

A small deposit can remain INCOMPLETE_DEPOSIT; do not assume it has been refunded. A late deposit may be refunded by 1Click, may still produce an accepted Annon purchase, or may reach Annon after purchase expiry. With a valid Annon refund identity, a delivery refused after expiry is refunded in full to that NEAR Intents account. Check both the saved swap status and Annon purchase status before taking another payment action. Source-chain refunds follow the quote's refund rules and may incur a fee.

Refunds in your NEAR Intents account

Refunds from the contract go to the NEAR Intents account of the wallet you bought with: your EVM address, your Solana key, or your NEAR account.

With a valid Annon refund identity, the contract records the refund for that identity's NEAR Intents balance. Crediting the balance is asynchronous; a transfer to Annon is not proof that the refund has already arrived.

Withdraw using a NEAR Intents interface that supports the same identity and its USDC balance. Annon's CLI and MCP server do not provide a refund-withdrawal command. If you cannot locate or withdraw the balance, contact hello@annon.dev with your purchase ID and transaction hash. Never send a private key, seed phrase or backup secret.

After you bought

Download limit reached

download_limited (HTTP 429): on the demo host, each purchase can download its file three times right away. After that you wait:

Download Available
1st to 3rd Right away
4th 15 minutes after the 3rd finished
5th 2 hours after the 4th finished
Each later one 24 hours after the previous one finished

retryAfterSeconds says how long to wait before requesting another download. Save the file once and keep it.

The host counts a download when it finishes transmitting the complete encrypted body. A later decryption or local-save failure does not undo that count. Interrupted transmissions do not count. Recovery on another device does not reset the count, and the initial automatic save uses one download.

The download was interrupted

A running SDK download can resume from its first unchecked chunk. The host allows an interrupted logical attempt to resume within ten minutes of its last transmitted byte and within thirty minutes of the attempt's start. Restarting the program does not preserve the client's checked-chunk offset: run open again with the saved purchase.

download_in_progress means another download of the same purchase is running; the SDK waits a few seconds and retries. Existing output files are not overwritten (output_exists); choose another output name.

Opening on a new device

Use the same wallet you bought with. You never pay again.

  • EVM or Solana: recovery costs you nothing.
  • NEAR account: prepay a little contract storage first. See NEAR accounts.

Configure the reviewed deployment, NEAR wallet and backup secret first. Replace account, purchase ID and file URL placeholders with your own values.

Shell
annon recover --wallet near --recovery near:YOUR_ACCOUNT.near
annon open 0xPURCHASE_ID --url https://demo.annon.dev/f/FILE --output file.pdf

The file was deleted from the demo host

Demo-host uploads expire seven days after first publication, except the configured canonical demo file. After expiry, new offers and downloads are refused with file_expired (HTTP 410); an already active download may finish. Keep your own copy. The demo itself runs until 18 November 2026, at the latest 19 November.

Your accepted purchase remains on chain. If another host serves the same checked encrypted file, use annon open 0xPURCHASE_ID --url https://OTHER_HOST/FILE --output file.pdf. For a local encrypted copy, use annon open file.pay2 --purchase /path/purchase-backup.json --output file.pdf.

The file was taken down after you bought it

A moderator's takedown blocks new key requests, including recovery. A request already sent to MPC can still complete. Keep any copy you have already opened. A valid NEAR or 1Click payment received after takedown is not accepted as a purchase and is refunded in full to its designated NEAR Intents account.

Report a problem

  • A security vulnerability: report it privately through the Security tab of the GitHub repository, then Report a vulnerability. Please do not open a public issue.
  • A file on the demo host, a missing refund, or anything else: write to hello@annon.dev.

Include the purchase ID, file ID, transaction hash and error code when you have them. Never send your backup secret, a private key or a seed phrase. We will never ask for them.

Synced from docs/what-can-go-wrong.md at commit e649de1. Also asMarkdown.