Troubleshooting
OAuth on SSH wedges
Section titled “OAuth on SSH wedges”The default OAuth flow needs a localhost browser callback. When you’re SSH’d into a remote box, that browser opens on the server and never reaches you.
mxr auto-detects this case (no TTY / SSH_CONNECTION set / no DISPLAY) and switches to the Limited Input Device flow (RFC 8628). Run the daemon in the foreground to see the device code:
# Terminal 1mxr daemon --foreground
# Terminal 2mxr accounts add gmail --account-name personal --email you@gmail.comIf the bundled OAuth client is configured as a Desktop app on Google’s side, device flow may fail with device_id errors. Drop down to IMAP+SMTP with an app password:
mxr accounts add imap \ --email you@gmail.com \ --imap-host imap.gmail.com \ --imap-username you@gmail.com \ --imap-password "$APP_PASSWORD" \ --smtp-host smtp.gmail.com \ --smtp-username you@gmail.com \ --smtp-password "$APP_PASSWORD"Generate the app password at https://myaccount.google.com/apppasswords (requires 2FA on the account).
Sync hangs or never completes
Section titled “Sync hangs or never completes”mxr sync acks as soon as the sync has started, so “hanging” is really “the account never goes idle”. Watch it with a wait long enough to outlast a backfill. First sync explains what you can search while it runs and how to verify local mail.
mxr sync --wait --wait-timeout-secs 900--wait-timeout-secs bounds the wait, not the sync: on expiry the command exits non-zero and the sync keeps running. A moving progress line (personal: 3,000/50,000 — Stored 3000 messages) means it is working; a stuck count means it is not.
If it times out with no movement, check the daemon logs:
mxr logs --level error --since 10m --format json | jq .Common causes:
- Provider rate-limit. When Gmail refuses a request with a rate limit, mxr makes no Gmail calls for that account until the retry time Gmail sent has passed. The sync loop checks again no later than an hour after a refusal. Sync, sends, label and flag changes, drafts and attachment fetches all wait. Each retry sent during the wait would restart Gmail’s window, so the wait is what ends the limit.
mxr status --format jsonshows the synclast_error: the refused endpoint, Gmail’s reason and the retry time, for exampleRate limited by Gmail messages.get (rateLimitExceeded: User-rate limit exceeded; 412 requests in the last hour) — retry after 1234s, and once the wait is running, when mxr resumes (Gmail asked mxr to wait until 02:12:52 UTC).mxr logshas one WARN line per refused request with the account’s Gmail request counts for the last minute and hour. A high count means mxr itself is making the requests. A restart clears the wait, so the first request after it can get one more refusal. - Gmail token refresh unavailable. A timeout, connection or TLS failure, a 5xx, or a token-endpoint reply mxr cannot read (the error names its HTTP status) is retried automatically and never starts a browser sign-in.
mxr statusreports it as “Can’t reach” andmxr doctoras a network finding. A token-endpoint 429 is reported as rate limited, and the daemon waits theRetry-Afterit sent (capped at five minutes). - Gmail token could not be saved.
Local token cache write failedmeans the refresh worked but the OS keychain or the token directory refused the write. The sign-in is intact, so do not re-authorize: unlock the keychain or fix permissions on the token directory (MXR_TOKEN_DIR, default<data_dir>/tokens).mxr doctorreports it as a storage finding. - Stale Gmail history cursor. mxr falls back to a full resync automatically. If it doesn’t, force one with
mxr doctor --reindex. - Stale IMAP/SMTP password. Run
mxr accounts repair <name>. It re-prompts for password-backed IMAP/SMTP credentials and writes them tosecrets.toml. The command can run directly from config when the daemon is unavailable, so a broken legacy keychain credential does not block its own repair. - Stale OAuth credential. When Google rejects the stored grant (
invalid_grant) status says the account “needs you to sign in again”. Runmxr accounts reauth <name>for Gmail or Outlook. OAuth tokens do not use the IMAP/SMTP repair path.
A sync that runs for hours
Section titled “A sync that runs for hours”A long sync (a large initial backfill, a slow IMAP server) is never cancelled mid-flight — cancellation could abandon the connection mid-command. It just keeps going:
mxr sync --statuskeeps showingIn progress: true, and--format jsoncarries aprogressobject with the running count.- A second
mxr syncwhile one is running joins the running sync instead of queueing another pass behind it, and acks immediately. - When the sync finishes, the status row is finalized normally (success or the real error) and the next sync can start.
No action needed — check again later:
mxr sync --status --format json | jq '.[] | {account_name, sync_in_progress, progress, last_error}'sync interrupted by daemon restart
Section titled “sync interrupted by daemon restart”If the daemon dies mid-sync (crash, kill -9, reboot), the next daemon start clears the stale in-progress flag and records failure_class: interrupted. The next sync cycle resumes from the last persisted cursor — no data is lost and no cleanup is needed.
Sent message isn’t searchable
Section titled “Sent message isn’t searchable”In v1+ this should never happen — the daemon inserts a synthetic Sent envelope immediately on send. If you upgraded from 0.4.x and a message is missing, force a resync:
mxr sync --waitFor SMTP+IMAP accounts: the synthetic Sent envelope is keyed differently from what IMAP-side discovery will produce on the next sync, which can leave a transient duplicate. This is a known v1 follow-up; the duplicate will be resolved by the next IMAP-side reconciler pass.
cargo install --locked mxr says “package not found”
Section titled “cargo install --locked mxr says “package not found””mxr is intentionally not published to crates.io — the workspace’s
internal mxr-* crates are organizational seams, not library APIs, and
publishing 22 crates per release was a poor fit for what mxr ships.
Install via Homebrew (recommended) or cargo install --git:
brew install planetaryescape/mxr/mxr# or (replace vX.Y.Z with the latest release tag)cargo install --git https://github.com/planetaryescape/mxr --tag vX.Y.Z --locked mxrSearch returns nothing for a query that should match
Section titled “Search returns nothing for a query that should match”First rule out the address operators. from:, to:, cc:, bcc: and deliveredto: match the whole address, case-insensitively — there is no partial or domain matching, and a partial still parses and returns zero:
mxr count "from:alice" # 0 — not an addressmxr count "from:alice@example.com" # what you meantOtherwise the Tantivy index can drift if a sync was interrupted before commit. Rebuild it from SQLite:
mxr doctor --reindexThen verify:
mxr count "your query"If the search is limited to the wrong account, check account selection and the CLI account-scope rules.
A message shows as flat text, or mxr doctor reports HTML helper fallbacks
Section titled “A message shows as flat text, or mxr doctor reports HTML helper fallbacks”mxr parses mail HTML in a separate helper process (mxr __html-worker) with a memory ceiling and a 5 second limit, so a hostile or enormous message cannot take the daemon down. When a message is over the HTML limits, makes the helper run out of time or memory, or the helper cannot start, mxr shows the message’s tag-stripped text instead. Tables and lists lose their layout; the words stay, and search still finds them. Links and images are not listed for that message.
mxr doctor shows the count in one line:
mxr doctor --format table | grep '^HTML helper:'# HTML helper: 2 fallbacks since start (4012 requests, 1 timeouts, 1 helper deaths, 2 restarts, 0 job errors)Each fallback is one request that got flat text. A count that climbs with ordinary mail suggests the helper cannot start: check that the mxr binary the daemon runs still exists, then restart the daemon. After an upgrade on macOS, a TUI or daemon that was already running keeps showing flat text until it is restarted, because it will not use a helper from the new release. While the helper cannot start, sending or forwarding an HTML message is refused with “try again in a few seconds”; a refusal that says the HTML is too complex means the helper gave up on that HTML, and simplifying it is the fix. HTML helper: not reporting means the daemon is not running or predates the helper. Open the message in your browser (O in the TUI) to see the original.
Agent access or model feature is refused
Section titled “Agent access or model feature is refused”For an agent tool refusal, check agent and MCP profile scope and paired-client authority. For a native mxr model feature that is disabled or uses a different endpoint, use LLM feature setup and routing.
Daemon won’t start
Section titled “Daemon won’t start”mxr daemon --foregroundForeground mode prints startup errors to your terminal. If it complains about a stale socket, the simplest fix is:
mxr restartmxr restart reaps the existing daemon, removes any stale socket, and brings a fresh one up against the same binary.
If it complains about a missing migration on the SQLite database, the local store schema is older than the binary. Either run mxr doctor (which applies pending migrations) or, as a last resort:
mxr reset --hard --dry-run # previewmxr reset --hard # destructive; preserves config + credentialsmxr reset --hard wipes local cache and the search index but keeps your account config and credentials. Re-run mxr sync --wait --wait-timeout-secs 900 after — that resync is a full backfill.
Local views take seconds to open
Section titled “Local views take seconds to open”Check the installed binary and daemon before resetting or reindexing:
mxr versionmxr status --format jsonmxr doctorAfter an upgrade, one-time projection backfills and startup maintenance can slow the first views. If status answers quickly but Messages is slow, the daemon is up and the delay is in building that view. Reindexing search does not fix a slow Messages list.
If you have a repository checkout, run the timing sweep from its root against your intended local runtime:
python3 scripts/perf-mail-views.py --repeat 3 --budget-ms 250The sweep changes no mail and prints timings and failure summaries only. Any sample can come from a cache, including the first. Follow Measure local mail views for the cache-layer checklist and isolated tests. Do not switch a development binary onto your normal mailbox or change real mail for a test.
If CLI requests are quick but the web app still appears to reload, inspect the
/api/v1/mail/people request in browser DevTools. Compare its response time
with the visible loading time and layout movement. Messages keeps its filter
controls and open conversation mounted while a view loads. Report a replaced
pane or shifting controls separately from slow replies.
Web app cannot reach mxr
Section titled “Web app cannot reach mxr”If the web app says mxr isn’t running. Showing what was loaded at 21:04.,
the page keeps what it had loaded, but new pages and changes need mxr to
answer. The banner’s Copy start command button copies mxr restart; run it
on the computer running mxr. If copying is unavailable, use the command below.
You can also check the connection and restart mxr there:
mxr statusmxr restartFor a remote bridge, check the tunnel or network connection before restarting the daemon. The banner clears when mxr is reachable again; you do not need to reload the page. A page that couldn’t load says what happened and what still works in plain words; expand Details under it to see the underlying error. A conversation or item that can’t be found offers Go to Inbox, not Try again, because asking again can’t change the answer. If the banner says Live updates are paused instead, mxr is answering but the event stream is disconnected: mail still loads, changes still work, and new mail appears when the stream reconnects. A proxy that does not pass WebSockets can cause that state.
Daemon unreachable after an upgrade
Section titled “Daemon unreachable after an upgrade”When you run a newly upgraded mxr binary, the first command restarts the daemon to match the new build. The restart waits for the old daemon to fully exit before starting its successor, and a shutting-down daemon never removes a socket it no longer owns — so the replacement daemon is reachable as soon as the restart message finishes.
On versions up to 0.5.62 this handoff could race: the old daemon’s exit cleanup deleted the new daemon’s socket, leaving a daemon that was alive and syncing but that no client could reach (the TUI would show an action status like Archiving... forever). If you hit that state on an old version, run any mxr command — it detects the missing socket and restarts the daemon — then retry the stuck action, which was never applied.