Fixing "Connection Reset by Peer" Migration Errors

A migration that was happily chewing through a 40 GB mailbox suddenly stops. The log shows ECONNRESET: connection reset by peer and the job pauses. The mailbox is still online, IMAP still answers a manual telnet imap.example.com 993, and your credentials are fine. Something on the path actively killed the TCP socket. This post walks through the three usual suspects — your egress firewall, NAT timeout, and provider-side throttling — and how to tell them apart in under ten minutes.

What "connection reset by peer" actually means#

ECONNRESET is a TCP-level error. The migration host received a packet with the RST flag set, which is the protocol's way of saying "this socket is over, do not send anything else on it." Unlike a timeout, which suggests the network silently went away, an RST is intentional. Someone — the server, a firewall, a load balancer — made the decision.

That distinction matters because the fix is different for each origin. A timeout might mean a flaky link. An RST almost always means a policy or limit was tripped. You will see this error appear in logs as any of:

• Error: read ECONNRESET
• IMAP connection closed unexpectedly: connection reset by peer
• socket hang up (the Node.js wrapper around the same condition)
• Connection reset by peer on Linux migration hosts

The IMAP layer above the socket has no opinion — it sees the connection vanish and bubbles the error up.

The three usual causes#

1. Stateful firewall killing long-lived IMAP sessions#

Corporate egress firewalls frequently cap how long a single TCP connection can stay open, even if data is actively flowing. The cap is sometimes documented as a session timer, sometimes as an IDS rule that flags long IMAP sessions as suspicious. Either way, the firewall sends an RST to both sides at the cap.

You will see the RST land at almost exactly the same elapsed time on every retry — for example, every connection dies at 58–62 minutes. That regularity is the giveaway.

2. NAT mapping expiring under load#

If the migration host is behind NAT — a home office router, a cloud VPC NAT gateway, a small-office SOHO box — the NAT table maintains a 5-tuple mapping per connection. Under memory pressure or with aggressive idle timers, the NAT entry expires while IMAP is mid-FETCH. The next packet from the server arrives with no matching mapping, the gateway sends an RST, and your migration drops.

This case tends to appear when many mailboxes are migrating at once and the NAT table fills up.

3. Provider proactively throttling your IP#

Large IMAP providers protect themselves by sending RSTs when one client exceeds a soft concurrency or bandwidth limit. The exact thresholds are not public and shift over time, but the symptom is consistent: bursts of resets that correlate with high parallelism on your side. See the IMAP throttling troubleshooter for the back-pressure handling Mailbox Taxi applies automatically.

A 10-minute diagnostic flow#

1. Read the log for timing patterns

   Pull the last 200 lines of the run log. Look at the elapsed time of each ECONNRESET. If every reset happens at roughly the same elapsed duration since connection open, suspect a firewall or NAT timer. If resets cluster when several mailboxes start at once, suspect provider throttling.

2. Drop concurrency to a known-safe floor

   Set per-mailbox connections to 2 and run only one mailbox at a time. If the resets stop, the cause was concurrency-related — either your own NAT or provider throttling. Slowly increase concurrency until you find the ceiling, then stay 30 percent below it.

3. Capture packets if needed

   On Linux or macOS, run tcpdump -i any -w reset.pcap host imap.source.example.com and port 993 for the next failing run. Open in Wireshark and filter on tcp.flags.reset == 1. The packet's source IP tells you which device killed the connection: if it is the IMAP server, it is provider-side; if it is one of your own hops, it is your network.

4. Enable OS-level TCP keepalive

   On Linux, set net.ipv4.tcp_keepalive_time=60 and net.ipv4.tcp_keepalive_intvl=30. On macOS, the equivalent sysctl net.inet.tcp.keepidle values do the same. This keeps NAT mappings warm and exposes broken paths sooner than a normal IMAP idle would.

5. Restart with resume enabled

   Restart the migration. Mailbox Taxi resumes from the last committed UID per folder, so the retry is not wasted work. Tail the log and watch whether the same elapsed-time pattern reappears.

For background on the IMAP commands underneath these connection mechanics — FETCH, IDLE, LOGOUT — the IMAP protocol glossary explains why long fetches keep a socket open in the first place.

What Mailbox Taxi does automatically#

The tool handles three layers of protection so you don't have to script them yourself:

• Per-connection retry with exponential backoff. A reset triggers a single retry after 5 seconds, then 15, then 45 seconds. After three failures the job pauses for manual inspection.
• UID-level resumption. Every successfully copied message commits its source UID to a local SQLite ledger. A restart picks up exactly where the reset hit.
• Adaptive concurrency. When the reset rate exceeds 1 in 50 message fetches, the worker pool shrinks itself by one and stays there for the rest of the run.

This means a single ECONNRESET in a long migration is normal and self-healing. A sustained pattern is what you need to act on.

When to involve the provider#

Some resets are not yours to fix. If the packet capture shows the RST coming from the IMAP server's IP, and concurrency is already at the floor, open a ticket with the provider. Include:

• The exact UTC timestamp of three reset events
• The source IP of your migration host
• The mailbox address (so they can pull server-side logs)

Most providers will tell you within a day whether you tripped a soft cap, hit IDS heuristics, or whether their load balancer was draining during your run. With that information you can either schedule the cutover for a quieter window or open a higher concurrency allowance for the migration period.

If TLS errors appear in the same log alongside the resets, treat them as a separate issue — the TLS handshake troubleshooter and the migration troubleshooting hub cover the cipher and proxy cases. For end-to-end IMAP migration mechanics, see the IMAP migration guide.