# 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`:

```bash
FOB_DEBUG=1 fob-email folders list
```

## Sign-in fails

```text
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](/docs/email/providers) 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](/docs/email/providers#icloud-mail).
- **Outlook.com or Microsoft 365.** These can't connect at all. See [Outlook and Microsoft 365](/docs/email/providers#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

```text
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:

```bash
fob-email config accounts add personal \
  --imap-host imap.gmail.com --imap-user you@gmail.com \
  --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

```text
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](/docs/email/connect). If you set `FOB_EMAIL_CONFIG_DIR`, the account must be in that folder's `config.yml`.

## Unknown account

```text
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

```text
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

```text
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

```text
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](/docs/email/cli/local-sync), and that folder hasn't been synced. Run the `sync run` command it suggests, or drop `--cached`.

## Local sync requires SQLite

```text
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

```text
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](/docs/email/cli/reference/emails).

## 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](https://github.com/finopsbricks/fob-email/issues) with the command, the error text, your provider and IMAP host, and your Node.js version. Leave out passwords, addresses and message contents.