WHM Transfer Tool: Move cPanel Accounts Between Servers
You've outgrown your current server, or you're moving a client's cPanel account to a new box, and someone mentions "just use the Transfer Tool." Then the transfer fails halfway through, or it finishes but DNS is pointing at the wrong IP, or email stops working for six hours. Here's what WHM's Transfer Tool actually does, where it breaks, and how to run a migration that doesn't wake anyone up at 2 a.m.
What the Transfer Tool Actually Does
WHM's Transfer Tool (under Transfers > Transfer Tool in WHM) connects to a source server over SSH or API token, runs pkgacct on each cPanel account you select, and streams the resulting archive straight to the destination server where it's unpacked with restorepkg. That one job carries files, the MySQL databases, email accounts and forwarders, DNS zone records, and cron jobs — everything tied to the account, not just public_html.
That's the appeal: it's a single admin-level operation instead of you manually rsyncing files, dumping databases, and re-creating mailboxes by hand. It's also why it can go wrong in ways a plain file copy never would — it's moving more moving parts at once.
Symptom: The Transfer Stalls, Fails, or "Succeeds" With Missing Pieces
The three complaints we hear most from admins running their first Transfer Tool job:
- The transfer queue shows a account stuck at a percentage for an hour with no progress
- The job finishes green, but logging into the account shows missing email, a broken database connection, or an empty
public_html - The site "moved" but visitors still hit the old server, or mail bounces for hours after the DNS change
Each of these has a specific, findable cause — it's rarely a random glitch.
Cause: Where Transfers Actually Break
1. Disk space on the destination
The destination server needs room for the full archive plus the unpacked account — effectively double the account's size during the restore. If the destination is already tight on space, restorepkg fails partway and you get a partially restored account with no clear error in the UI, just a red status line in the transfer log.
2. Package/plan limits don't match
If the destination's hosting package caps disk space, email accounts, or databases below what the source account actually uses, WHM will restore what it can and silently skip or truncate the rest. This is the single most common cause of "email is missing" after a transfer — the account got restored under a package with a lower mailbox limit.
3. Version mismatch between servers
Restoring a MySQL 8 dump onto a server still running MySQL 5.7, or a PHP 8.2 account onto a server that only has 7.4 installed, restores the files fine but leaves the site broken until you fix the PHP/MySQL version on the new account manually.
4. DNS and mail don't move at the same moment
The account transfer itself takes minutes. Updating nameservers or A records, and having that change propagate, takes hours. If you flip DNS before verifying the new account is fully working, or you flip it and forget the old server is still receiving mail during propagation, messages sent in that window can bounce or get delivered to the wrong box.
Fix: Running a Clean Transfer Step by Step
Step 1 — Check destination capacity first
Before queuing anything, SSH into the destination and check free disk space against the source account's actual usage:
df -h /home
du -sh /home/usernameLeave real headroom — at least 1.5x the account size — not just barely enough to fit the compressed archive.
Step 2 — Match or exceed the source package limits
In WHM, check the source account's package under List Accounts, then either use the same package name on the destination or create one with equal or higher limits before you transfer. The Transfer Tool interface lets you remap which package a restored account lands under — don't leave it on a default that's smaller than what the account needs.
Step 3 — Queue the transfer with the right options
In WHM: Transfers > Transfer Tool, add the source server (hostname, root credentials or API token, port), select the accounts, and before you hit start, check these boxes:
- Restore to same account name unless you specifically need to rename
- Skip existing accounts only if you're re-running a partial transfer, otherwise it can leave stale data mixed with new
- Leave DNS as-is on the destination for now — don't let the tool touch live DNS until you've verified the account
Run it in small batches (5-10 accounts at a time) rather than all 200 at once. A batch failure is much easier to diagnose than digging one broken account out of a 200-account job.
Step 4 — Verify before touching DNS
On the destination, before changing a single nameserver, confirm the account actually works:
- Edit your local
hostsfile to point the domain at the new server's IP and load the site directly - Log into the new account's webmail or an email client using the new server's mail settings to confirm mailboxes and messages came across
- Check
Cron Jobsin the restored account's cPanel against the original
Step 5 — Cut over DNS with a short TTL
Drop the domain's A record TTL to 300 seconds a day ahead of the cutover if you can. Then update the A record (or nameservers) and keep the old server running, untouched, for at least 48 hours — that's your safety net if propagation is slow or something surfaces late. Only decommission the old server once mail flow and site traffic have clearly moved to the new IP in your access logs.
Common Transfer Tool Errors
| Error / Symptom | Likely Cause | Fix |
|---|---|---|
| "Insufficient disk space" mid-restore | Destination doesn't have 2x account size free | Free up space or resize the volume before retrying |
| Transfer shows complete, mailboxes empty | Destination package's email account limit was lower than source usage | Raise the package limit, re-run transfer for that account only |
| Site loads but shows a database error | MySQL version mismatch or database user privileges not restored | Check MySQL error log, re-grant privileges via phpMyAdmin or WHM's MySQL page |
| Job hangs at a fixed percentage | SSH connection to source dropped, or one huge file (large backup, log) is still streaming | Check the transfer log for the specific account, retry that account alone |
| Mail bounces for a few hours post-cutover | MX records still pointed at old server during propagation window | Keep old server's mail queue running during the TTL window; don't shut it down early |
Prevention: Make the Next Transfer Boring
- Always run a test transfer of one small, low-risk account first before queuing the rest
- Match PHP and MySQL versions on the destination to the source before transferring, not after
- Keep the source server alive and untouched for 48+ hours after cutover
- Document package limits on both servers side by side so nothing gets silently downgraded
Done this way, the Transfer Tool genuinely is the fastest, cleanest way to move cPanel accounts between servers — the failures almost always trace back to a mismatched package limit or disk space, not the tool itself.
Frequently asked questions
Does WHM's Transfer Tool move email messages, or just mailbox configuration?
It moves the actual mail stored on the account's disk under the mail directory, not just the account settings, as long as you're using full account transfer rather than a partial or files-only option. If mail seems missing afterward, check whether the destination package's email limits were lower than the source's actual mailbox count first.
Can I use the Transfer Tool between two different WHM/cPanel versions?
Yes, within reason — cPanel supports transfers across recent version differences, but a large version gap (several major versions apart) increases the odds of restore warnings for things like PHP handlers or Apache config. Check cPanel's compatibility notes for your specific source and destination versions before a big batch.
How long should I keep the old server running after a transfer?
At least 48 hours after DNS cutover, and longer if your domain's previous TTL was high. This covers slow DNS propagation and gives you a fallback if an issue only shows up under real traffic.
Why did only some email accounts transfer, not all of them?
This is almost always a package limit mismatch — the destination account's hosting package capped the number of email accounts below what the source actually had. Raise the limit on the destination package and re-run the transfer for that account.
Is the Transfer Tool safe to run on a live, in-use account?
Yes — pkgacct reads the account without taking it offline, so the source keeps serving traffic and mail during the copy. The risk isn't the copy itself, it's cutting DNS over before you've verified the destination account is fully working.