anona doctor --space YOUR_SPACE # which credential wins, does the server answer, is the space reachable, credits left
anona --version # is this the copy you think it is
anona:. The exit codes are on Scripting & automation.
Install and version
| Symptom | Cause and fix |
|---|---|
invalid choice: 'record' (or any command) | The anona on your PATH is older than the command, or it is the npm package, which does not have it yet. pip install -U anona, or run uvx --from anona anona <command>. anona --help lists what your copy has; What each package has lists both packages |
error: externally-managed-environment | pip refusing a system Python. Use uvx --from anona anona ... or pipx install anona |
pip install anona succeeded, still the old version | pip does not upgrade an installed package without -U |
Two different anona behaviours on one machine | Both the pip and the npm package are installed; whichever is first on PATH wins. which -a anona |
Credentials (exit 4)
| Error | Fix |
|---|---|
anona: no credential. ... | Run anona login --cli, set ANONA_API_KEY, or anona start for a temporary profile |
the stored `anona login` credential is for MCP | You signed in for MCP only, which the REST API refuses. anona login --cli |
refusing to send the API key from ANONA_API_KEY to <host> | A key only goes to api.anonalabs.com / memory.anonalabs.com unless the server is named in the same place as the key. Pass --api-key and --base-url together, or unset ANONA_BASE_URL. See Where a key may be sent |
the stored credential is for https://..., not https://... | A login only goes to the server that issued it. anona login --base-url https://other-host to switch |
invalid_api_key / key_expired | The key was revoked or expired. Mint a new one under API keys |
| A command fails with an authorization error after weeks unused | The login’s refresh token lapsed after 30 days of silence, or was revoked. anona login --cli |
space_owner_only / space_read_only | The space is shared with you without that right. Ask its owner |
temp_profile_single_space | A temporary profile has one space, default: it cannot create spaces or write anywhere else. Omit --space, or sign in with anona login for more |
Usage (exit 2, nothing sent)
| Error | Fix |
|---|---|
an API key needs a space | Pass --space NAME or set ANONA_SPACE_ID. anona spaces list shows them |
this would delete ... Pass --yes to do it | Destructive commands need --yes. Confirm with whoever owns the data first |
--batch line N: ... | That line of the JSON Lines file is not valid JSON, has an unknown field, or has an empty content. Nothing was sent; fix the line |
--wait needs --async or --batch | A plain record already waits |
name at least one field to change | A settings set with no field. See How set works |
invalid choice / unrecognized arguments | A flag your copy does not have. anona <command> --help or anona guide |
Not found (exit 5)
| Error | Fix |
|---|---|
space_not_found | Check the id with anona spaces list. A space shared with you may need its owner:name form. A read never creates a space, so a space nothing was written to yet does not exist |
space_ambiguous (exit 1) | The bare name is both yours and a share; use the qualified_id from anona spaces list |
memory_not_found | Misspelled, or already deleted |
job_not_found | jobs get or a --wait on an id that is not a job in this space. Check --space; the API reports this as 200 with "status": "not_found" |
Rate limits and credits (exit 6)
| Error | Fix |
|---|---|
rate_limited | The per-minute ceiling. The CLI already retried with backoff; wait and run it again |
credits_exhausted | The plan allowance and any top-up are spent. Reads spend credits too, so retrieve, reason, memories list, documents list and profile are refused at zero as well as writes. anona usage (or anona doctor) shows the balance |
Unavailable (exit 7)
| Error | Fix |
|---|---|
could not reach <host> | Network, proxy or DNS. anona doctor checks the server’s health without sending a credential |
write_status_unknown, or a timeout on a write | The write may have been stored. The CLI never re-sends a write after a timeout or 5xx. Check with anona retrieve or anona memories list --q before running it again |
reason_timeout | The question took too long over this space. Ask something narrower, or retry with --depth fast |
delete_unavailable | The memory was not deleted. Retry |
Other
| Symptom | Fix |
|---|---|
record exits 3, “nothing was stored” | Not an outage: no fact could be extracted from that text. Re-record with a sentence of context |
--wait exits 8 | The job is still running. anona jobs get JOB_ID --space ... later |
documents upload fails with unsupported_file_type / file_too_large / upload_too_large | The server’s message names the supported types and the limits. See documents |
A scoped retrieve misses memories you know are there | Scoped search is strict: memories written without that --user-id are not returned. Write and read with the same scope |
reason seems to hang | It is an agent loop and takes tens of seconds; it says so on stderr. --timeout caps one request (default 120 s) |