The symptom
Mail opens. Your mailboxes are listed. Messages appear when you click a mailbox. But search returns nothing, or almost nothing, for mail you know is there. Sometimes Mail offers to import your mailboxes on every launch, gets most of the way through, and then stops with:
An error occurred during the import — make sure you have available space in your home folder.
You check. You have hundreds of gigabytes free. You empty the Trash anyway. You restart. Mail offers to import again.
Free space has nothing to do with it.
What Mail is actually doing
Everything Mail knows about your messages — sender, subject, date, read state, which mailbox a message is in, and the search index itself — lives in one SQLite database:
~/Library/Mail/V10/MailData/Envelope IndexV10 is the mail library version and it moves with macOS releases — yours may use a different version number.
The messages themselves are separate, stored as individual .emlx files on disk. This matters, and it is the reassuring part of this whole story: a broken index does not mean lost mail. The mail is still there. What is broken is the catalogue.
When macOS updates the format of that catalogue, Mail rebuilds it. It does not rebuild in place — that would risk leaving you with a half-written index if anything went wrong. Instead it builds a complete new database alongside the old one, under a temporary name:
Envelope Index..tmp.0Vc9XkWhen the rebuild finishes, Mail is supposed to complete a final installation step and begin using the rebuilt catalogue.
Why it can never succeed
On a Mac in this state, three things are true at the same time:
- The live
Envelope Indexis 4 KB and contains no tables at all. It is an empty shell. - Beside it sits
Envelope Index..tmp.<random>containing a complete, fully populated schema — around 55 tables, all your mail catalogued. - Mail insists the import failed.
The import did not fail. The import succeeded. Only the final installation step failed.
This is not an inference. Mail’s own logs record the rebuild completing, and the installation step failing immediately afterwards, on every attempt.
And it does not resolve itself. Every retry rebuilds the catalogue again and leaves another complete copy on disk under another random name, none of which ever becomes the live index. On the machine where this was investigated, the oldest abandoned rebuild dated from 2021 — four years of Mail trying, succeeding, and failing to finish.
That is the whole fault: the work is done, the result is sitting on disk, and the handoff is the part that cannot complete. Apple's own Mail upgrader cannot finish it, and there is no menu item, no preference, and no Mail Connection Doctor step that will.
The error message points the wrong way
"Make sure you have available space in your home folder" sends everyone who reads it to Disk Utility, or to a cleaner app, or to deleting things they wanted. None of that can help, and some of it does harm — the abandoned ..tmp. rebuilds are, at a glance, exactly the kind of large mystery file a person clearing space is tempted to delete, and the newest one is the only completed rebuild of your catalogue currently on disk. No mail is at risk if it goes — the catalogue is derived data, and Mail will build another on the next launch, exactly as it has been doing all along. What you lose is a finished import, and on a large library that is hours you did not need to spend.
If you take one operational thing from this: on a Mac in this state, the newest Envelope Index..tmp.* file is the most useful file in your Mail library. Leave it where it is. Mail can replace it, but there is no reason to make it.
How to check your own Mac
Download KNZŌ and run the free scan. Detection is read-only: KNZŌ checks the live index and its rebuild candidates, explains what it found, and changes nothing. If it does find this fault, the repair is free too — no licence, no trial.
Most Macs will report a healthy index. That is the expected outcome and it is worth saying plainly, because a field note like this can prime people to go looking for a problem they do not have.
Why this is recoverable
The important thing about this failure is what it is not. Nothing was lost. The rebuild worked, the database is complete, and it is sitting on your disk right now. What failed is the last step — moving it into place — and a step that failed is a very different problem from data that is gone.
That is why this is worth writing about rather than filing under "Mail is broken again". Your mail is intact, your catalogue is intact, and the two are simply not connected to each other.
Do not try to reconnect them by hand. A manual attempt can select the wrong rebuild, alter an active Mail library, or leave the catalogue in a worse state. The value is not merely changing a filename; it is proving that the candidate is complete, preventing concurrent Mail activity, preserving the prior state, verifying the repaired index, and rolling back automatically if any check fails.
The exact repair sequence is deliberately not published here, and that is not so we can sell it — KNZŌ performs the guarded repair for free, with no licence required. The procedure stays unpublished because the failure modes are unforgiving and a half-followed attempt on a live Mail library can leave it in a worse state than it started. Scanning, diagnosis, and every explanation are free as well.
What KNZŌ does with this
KNZŌ detects this state, explains it, and can complete the handoff. Specifically:
- Detection and repair are both free — KNZŌ evaluates the live index and eligible rebuild candidates, then reports what it found. Completing the repair needs no licence either. macOS caused this failure and cannot finish the fix itself, and we are not going to charge you to undo it.
- It refuses to act while Mail is running — no exceptions, and no setting to override it.
- It verifies before it commits — the rebuilt index is checked for a real schema and passed through a SQLite integrity check before it is installed.
- The repair is transactional — your existing index is snapshotted, the repaired index is read back and verified, and KNZŌ rolls the entire operation back automatically if verification fails. Your previous index is preserved as a recovery backup, and restoring it needs no licence. We are not going to hold the state you are leaving behind a paywall.
- It never deletes messages — not your mail, not your mailboxes, not the live index. Files KNZŌ moves go to the Trash with their original path recorded, and emptying the Trash stays your decision.
KNZŌ holds Full Disk Access and uses it to read your disk and tell you what it found — on your Mac, and nowhere else. No analytics, no telemetry, no crash reporting, no licence server.
What we don't know
How often this happens. We have confirmed it on one Mac. We have no basis for saying it is common, rare, or anything in between, and we are not going to add telemetry to find out — "no analytics" is a promise, not a slogan, and quietly instrumenting the answer would falsify it the day it shipped.
So the honest position is: this is a real, reproducible, precisely identified failure, and its prevalence is an open question. If KNZŌ reports it on your Mac, the diagnostic details are genuinely useful to us. A healthy result is expected and requires no action.
Written by Salman Sajid, who builds KNZŌ for macOS. Corrections welcome — if something here is wrong about how Mail behaves, we would rather know: support@swazzi.app