Troubleshooting¶

Startup and configuration¶

`PROTON_BRIDGE_USER is required`¶

Set the address in the environment inherited by the CLI or MCP client:

export PROTON_BRIDGE_USER="your-address@proton.me"

An integer setting is rejected¶

All numeric settings must be positive integers within the limits in Configuration. Remove the override to return to the safe default.

Bridge connection¶

`No Proton Bridge password found`¶

Ensure PROTON_BRIDGE_USER exactly matches the address used during setup, then run:

proton-safe-mcp setup

The credential is keyed by that address in the OS keyring.

Check that:

Proton Mail Bridge is installed, signed in, and running.
PROTON_IMAP_PORT matches the IMAP port shown by Bridge.
The stored password is the Bridge-generated IMAP password, not the Proton account password.
No sandbox prevents the local process from connecting to 127.0.0.1.

If Bridge regenerated its credential, run setup again.

Folders and messages¶

A folder cannot be opened¶

Call list_folders and pass the exact returned name. Folder input is validated and the mailbox is opened read-only.

A message is missing from a short list¶

Increase limit up to 100, use search_messages, or select a different folder. Results are newest first.

A body is truncated¶

Increase max_chars on read_message, up to 100000. Large output remains bounded by design.

Attachments¶

See Common attachment failures for filename, MIME, ordering, size, hash, and expiry errors.

Do not retry one chunk with the same index after the server has accepted it. Resume with the returned next_chunk, or discard and restart the upload if client state is uncertain.

Draft approval¶

`Unknown draft proposal or server was restarted`¶

The body is kept only in process memory. Prepare a new proposal after any server restart.

`Draft proposal expired`¶

Prepare and approve a new draft within PROTON_MCP_DRAFT_TTL_SECONDS.

`Local approval required`¶

Run the exact approval_command returned by prepare_draft in a separate local terminal.

Approval does not match¶

The approval marker digest differs from the in-memory proposal. Reject it and prepare a new draft; do not modify approval state manually.

Documentation build¶

Install the documentation extra and build with warnings treated as errors:

uv sync --extra docs
uv run mkdocs build --strict

Preview locally with:

uv run mkdocs serve