Fixing IMAP NO Permanent Failure Errors During Migration

The migration log shows * NO [ALERT] Mailbox is in a permanent failure state or A042 NO APPEND failed: permanent error. The wording sounds final, and that's the point — the server is telling your migration tool not to retry until something changes. The trick is that what needs to change is rarely on the migration tool's side. This post breaks down the three states that produce a permanent-failure NO response, how to tell them apart, and what to do about each.

What "permanent failure" actually signals#

IMAP responses come in three flavors. OK means the command succeeded. BAD means the server didn't understand the syntax. NO means the server understood and refused. The text after NO is human-readable and varies by server — but when it includes the word "permanent" or response codes like [ALERT], [LIMIT], or [UNAVAILABLE], the server is hinting that retrying the same command immediately is wasted work.

The word "permanent" is misleading. What it really means is: the current state of the mailbox makes this command impossible. Fix the state, and the command succeeds. There are three states that produce this kind of response in a migration context, and each has a different fix.

State 1: Source mailbox in repair or scan mode#

Providers run integrity scans on mailboxes when they detect index corruption, abnormal access patterns, or a recent crash. Large parallel IMAP reads — which is exactly what a migration looks like — can trigger this defensive behavior. The mailbox becomes read-only or partially unavailable until the scan finishes, usually within 10 to 60 minutes.

You'll see:

• NO [UNAVAILABLE] Mailbox is being checked, please try again later
• NO [SERVERBUG] Internal error, mailbox temporarily unavailable
• NO Mailbox is in maintenance mode

The fix is patience. The migration tool's exponential backoff will eventually reconnect successfully. If the state lasts more than an hour, contact the provider with the mailbox address and the UTC timestamp of the first failure. They can usually clear the scan flag manually.

State 2: Destination refuses APPEND due to message flags#

The destination is allowed to reject an APPEND for policy reasons: the message is too large, the destination quota is full, the message contains a forbidden attachment type, or the message-level flags violate destination rules. The error wording differs by destination:

• NO Message too large for destination — see the message too large troubleshooter
• NO Quota exceeded — see the quota exceeded troubleshooter
• NO APPEND refused: attachment policy
• NO [LIMIT] Mailbox over its quota

This state needs an explicit action. The migration tool can skip the offending message and continue with the rest of the mailbox, but the message itself won't migrate until you either change the destination policy or accept the skip.

State 3: Provider put the mailbox into read-only mode during cutover#

This one is the most surprising the first time you see it. Some providers — especially when the user's primary MX is being changed — will switch the mailbox to read-only as part of the cutover. The mailbox is still readable via IMAP, but APPEND, EXPUNGE, and any write operation gets a NO response.

If the destination is the affected mailbox, the migration cannot continue until read-only is lifted. Usually this is part of the provider's own cutover sequence — wait for it to complete, often 5 to 30 minutes, then resume.

The diagnostic flow#

1. Capture the exact NO response

   Open the migration log and find the full IMAP response line. The text after NO matters — NO [LIMIT] is a quota issue, NO [UNAVAILABLE] is a transient mailbox state, NO APPEND failed with no bracketed code is usually a destination policy. Note the response code if there is one.

2. Identify the responsible side

   Scroll up a few lines in the log. The IMAP command preceding the NO tells you which side issued it. UID FETCH errors come from the source. APPEND and CREATE errors come from the destination. SELECT errors can be either, but the connection identifier in Mailbox Taxi's structured log names the side explicitly.

3. Sign in to the affected mailbox via the web UI

   Open the web interface for whichever provider's mailbox is failing. Look for banners or warnings: quota meters in the red, a maintenance notice, a read-only badge. If the user has multiple devices syncing the mailbox heavily, sign them out temporarily to reduce load.

4. Wait or act based on the state

   Repair and maintenance states clear themselves — give it up to an hour, then re-test. Quota states need cleanup at the destination or an admin-side quota bump. Read-only states tied to a provider cutover clear on their own when the cutover completes. Any of these states is fixable, but the migration tool cannot fix them for you.

5. Resume the migration

   Restart the job. The UID ledger ensures messages already copied are not retried — only the previously-failed UIDs and any unattempted ones move. If specific large messages keep failing with permanent errors after the underlying state is healthy, treat them as individual exceptions and use the message-too-large or per-message troubleshooting flow.

What Mailbox Taxi does on your behalf#

When the tool sees an IMAP NO with a permanent-failure code, three things happen automatically:

• The failing UID is recorded in the run's error ledger with the full server response
• Backoff for that mailbox doubles to a 5-minute floor before the next attempt, so you don't pound a struggling server
• The rest of the mailboxes in the job continue normally — a single mailbox in a repair state doesn't stall the whole batch

After the run, the error ledger groups failures by response code so you can fix them in bulk: all the quota cases together, all the message-too-large cases together, and so on. That's a much better workflow than scrolling through a 20 GB raw log line by line.

For background on the IMAP commands that get refused — APPEND, FETCH, SELECT — the IMAP protocol glossary explains what each does and why a server might refuse it. For the broader end-to-end migration procedure, the IMAP migration guide walks the full job from connection through cutover. And for the catalog of every common migration error keyed by symptom, the troubleshooting hub is the index page.