← Contents
Start with these three; between them they explain most problems:
mailcoded health # store, secret backend, gates, per-account state
mailcoded account test # does the credential still work? IMAP and SMTP, separately
mailcoded stats # counters, the outbox, sends left this hour
In the TUI, S shows the same on one screen, including each account’s last error, and A runs the
connection test.
You see It means Do
No account is configured. Run 'mailcoded setup' first.the store has no accounts chapter 2 'setup' is interactive and needs a terminal.setup was run from a script, or with redirected inputuse account add --password-stdin 'mailcoded-tui' was not found beside this binary or on PATH.the TUI binary is not installed next to the CLI scripts/install.sh, or run mailcoded-tui from the build output directly (chapter 1)The TUI needs a terminal; stdin or stdout is redirected.mailcoded tui inside a piperun it in a terminal; scripts use the one-shot verbs This console cannot render ANSI. Try Windows Terminal. (exit 2)the legacy Windows console use Windows Terminal
You see It means Do
a login failure from setup, with hints wrong host or port, or the provider wants an app password read the hints; most providers reject the account password over IMAP (chapter 2) Microsoft did not return a sign-in code within 45s. Check the network, then try again.the device-code request did not complete check connectivity to login.microsoftonline.com; try again the Microsoft consent page names another application mailcoded borrows a public client registration expected; use --client-id with your own registration if you prefer (chapter 2) account test reports IMAP ok but SMTP authyou can read; the SMTP server rejected the credential sending fails until it accepts; reading is unaffected. For Microsoft accounts this is a known open issue at the time of writing The new credential was stored but the server still refuses it: ...reauth stored it; the server said nothe reason follows; exit 7 is authentication, 8 is network
You see It means Do
sync: Timed out connecting to <host>:<port>.nothing answered at that address a wrong host, a firewall, or the import-only account (chapter 10) This account has no stored credential, so it cannot sync. ...the account was registered without a credential, or is the local import account mailcoded account reauth --account <id>, or leave itLive updates belong to another mailcoded window; press r to refresh here.another daemon owns this store’s live connections normal with two TUI windows; r refreshes (chapter 9) Another live daemon (pid N) owns this store; watch connections stay closed here. (stderr)the same, from the daemon’s side any other red sync: ... the server refused, or failed A or account test for the detail; S for the last errorStill <something>. Press esc to give up on it.a server operation is slow wait, or esc to cancel it The daemon is gone: ..., TUI exits 3the daemon process died the TUI prints the daemon’s recent stderr as it exits; run it again; mailcoded-tui --check
You see It means
(body not fetched) in the readerthe body could not be downloaded just now (this message has no plaintext part)it is HTML-only; there is no HTML view � in a subject or bodythe message contained control or invisible characters (chapter 12) matches were dropped that no cursor reachesa search hit the paging ceiling; narrow it, or order by date
You see It means Do
Sending from the agent surface requires MAILCODED_SEND=1. (exit 4)the CLI send gate is closed chapter 7 — or send from the TUI, which is not gated this way exit 6, confirm-required no valid token: missing, spent, expired, or the draft changed send-preview againThat confirmation is spent or expired. Preview again. (TUI)the same ctrl-s againexit 5, rate-limited five sends this hour already wait retry_after_ms a recipient refused not on MAILCODED_APPROVED_RECIPIENTS add it, or send from the TUI outbox shows failed with an SMTP replythe server rejected the message the reply says why
You see It means Do
Moving mail is outside the default agent posture. ...move or archive from a script, without MAILCODED_ALLOW_MOVE=1 and --yesset the variable; add --yes for an unattended run Moving mail is not part of the agent surface. (exit 4)you confirmed at the terminal, but MAILCODED_ALLOW_MOVE is not set — the CLI is an agent surface MAILCODED_ALLOW_MOVE=1 mailcoded move ..., or use m in the TUIThis account has no folder marked as Archive.the server exposes no Archive role move --folder <name>No folder called 'X'. This account has: ...a typo, or a folder that has not synced yet pick from the list; sync A message can only move within its own account. (TUI)you picked a folder under another account pick one under the same account you are looking for delete there is none, by design chapter 6
You see Do
Raw SQL reads require MAILCODED_ENABLE_SQL=1. (exit 4)set it, or use search, read and thread
Code Retry?
0 success 1 internal error report it 2 validation — bad arguments fix the command 3 not found — no such message, folder, account or draft 4 forbidden — a safety gate refused no; open the gate deliberately, or don’t 5 rate limited after retry_after_ms 6 confirm required — send needs a valid one-time token preview again 7 auth — the credential failed or is missing account reauth8 network — transient yes, with backoff 9 store — the database is corrupt or full 10 unsupported — the server or this build lacks a capability 130 cancelled
The daemon logs to stderr. When the TUI exits because the daemon died it prints what the daemon
said; to drive the daemon by hand, mailcoded-daemon --log-level debug.
mailcoded health --json and mailcoded stats --json are the complete pictures.mailcoded-tui --check proves the wire without a screen.
A fresh sync from the server is always valid. mailcoded account forget --account <id> removes the
local copy — including your local Tags and drafts for that account — and mailcoded setup re-adds
it. If the store itself is damaged (exit 9), move the data directory aside and set up again; the
server still has your mail.