Troubleshooting

Errors print on stderr as Error: …, and the command exits with status 1. To see the full technical detail, run the command again with FOB_DEBUG=1:

FOB_DEBUG=1 fob-email folders list

Error: Sign-in failed ([AUTHENTICATIONFAILED] Invalid credentials (Failure)). Most providers need an app password, not your normal password. See …

The text in brackets is your provider's reason, so it varies. Versions before 0.2.0 printed only Error: Command failed.

You used your normal password. Most providers reject it over IMAP. Create an app password and use that.
Typo or extra characters. Copy the app password again. Spaces in Google's 16-character passwords are optional, but nothing else should be added.
The app password was revoked. Changing your account password revokes app passwords at Google and Apple. Create a new one and run config accounts add again with the same account name; it replaces the saved account.
Wrong username. Use your full email address, except for iCloud IMAP, which uses the part before the @. See iCloud Mail.
Outlook.com or Microsoft 365. These can't connect at all. See Outlook and Microsoft 365.
Google Workspace. Your administrator may have turned off IMAP or app passwords for your domain.

After fixing it, fob-email config accounts refresh <name> signs in again and updates the saved account details.

Connection errors#

Network errors end with Check the host name and port. and a link here.

Message contains	Check
`ENOTFOUND`	The host name. Use the exact IMAP host from your provider, with no `https://`, spaces or port.
`ECONNREFUSED`, `ETIMEDOUT`, or the command hangs	The port, and whether your network or VPN blocks it. IMAP uses 993 and SMTP 465 or 587.
A TLS or certificate error	Port 993 needs TLS on (the default). Don't turn TLS off for a provider that requires it.

Sending fails but reading works#

Error: Sending needs an SMTP server, and this account has none. Add the account again with --smtp-host (for example smtp.gmail.com), or set smtp.host in FOB_EMAIL_ACCOUNTS. See …

The account was added without --smtp-host. (Before 0.2.0, fob-email tried your IMAP server instead and failed with a confusing connection error.) Add the account again with the SMTP host:

fob-email config accounts add personal \
  --imap-host imap.gmail.com --imap-user [email protected] \
  --imap-pass "<app password>" --smtp-host smtp.gmail.com

If your provider's SMTP uses port 587 (iCloud, and some others), also pass --smtp-port 587 --no-smtp-secure.

If the send succeeds but some recipients print under Rejected:, the server refused those addresses. The others were sent.

No email account configured#

Error: No email account configured. Run `fob-email getting-started` for setup steps, or `fob-email config accounts add <name>`, or set FOB_EMAIL_ACCOUNTS (…/config.yml).

Add one with Connect a mailbox. If you set FOB_EMAIL_CONFIG_DIR, the account must be in that folder's config.yml.

Unknown account#

Error: Unknown account "work" (checked FOB_EMAIL_ACCOUNTS env and …/config.yml)

The name after --account doesn't match any account. Run fob-email config accounts list to see the names.

Message not found#

Error: Message not found: 1423

Message IDs belong to one folder. Pass the folder the ID came from with --folder: an ID from emails list --folder Archive needs --folder Archive on show, move or delete. A message also gets a new ID when it moves, so list the destination folder again to find it.

Message id is stale#

Error: Message id is stale (folder "INBOX" was reset) — re-list the folder to get fresh ids.

Your provider renumbered the folder. Run emails list again and use the new IDs.

No local copy of a folder#

Error: No local copy of "INBOX" for account "personal". Run `fob-email sync run --folder INBOX` first, or drop --cached to read live.

--cached reads only from the local mirror, and that folder hasn't been synced. Run the sync run command it suggests, or drop --cached.

Local sync requires SQLite#

Error: Local sync needs Node.js 22.13 or later for its built-in SQLite (this is v22.12.0). Upgrade Node.js, or use the live (non-cached) commands. See …

Upgrade Node.js to 22.13 or later. Every command without sync or --cached works on your current version. (Before 0.2.0 this message asked for Node 22.5, which isn't enough.)

Full-text search with --cached#

Error: Full-text search needs the server (the local mirror stores envelopes, not bodies). Drop --cached, or search --from/--subject instead.

The local mirror doesn't store message bodies, so a search query only works live.

Refusing to delete without --yes#

Deleting a message, draft or folder, and clearing the local mirror, all need --yes (-y). This stops a script deleting by accident.

Unknown arguments#

fob-email rejects flags it doesn't know. For example, there's no --unread on emails list: use --unseen. Check a command's flags with --help, or in the command reference.

fob-email --version shows the wrong version#

Versions before 0.2.0, installed as a dependency of another project, could print that project's version. Update with npm install -g @finopsbricks/fob-email@latest, or check the installed version with npm ls @finopsbricks/fob-email.

Still stuck?#

Open an issue on GitHub with the command, the error text, your provider and IMAP host, and your Node.js version. Leave out passwords, addresses and message contents.