File search not working: what to check, in order

A file that was open yesterday returns nothing today. The name is typed correctly, the disk is mounted, the file is visible in the folder when opened by hand, and the search box stays empty. The usual response is to rebuild the Spotlight index, which takes hours and fixes a minority of cases. The checks below are ordered by what they cost, so the expensive one comes last. Most of the time the answer is found in the first three, and none of them require waiting.

Name the symptom before changing anything

"Search is broken" covers at least four different faults, and each points at a different check. Sorting the symptom first prevents an hour spent on the wrong layer.

Symptom	Most likely layer	First check
Nothing at all is returned, for any query	Indexing state of the volume	mdutil -s on that volume
One folder never appears, everything else works	Exclusions	Spotlight privacy list
The name matches but the contents never do	Importer or file format	Whether the file holds real text
Results are there but out of date	Index staleness	Whether indexing finished
It worked before an upgrade or a migration	Indexing still in progress	Time, then the volume status

The most useful distinction is between a total failure and a selective one. A total failure is almost always about a volume or a permission, which is a single setting. A selective failure is about scope, exclusions, or a property of that one file, which is rarely fixed by anything global. Rebuilding the index in response to a selective failure usually changes nothing, because the item was never a candidate for the catalogue in the first place.

Check the query before blaming the index

The cheapest check is the text that was typed. Multiple words behave differently depending on whether they are quoted, and the behaviour is documented rather than incidental. Apple's page on searching your Mac returning unexpected results states that quoting a phrase matches the phrase as a whole, while leaving the quotes off matches items containing those words in any order.

That produces two distinct failures. A quoted phrase returns nothing when the actual wording differs slightly from memory. An unquoted phrase returns a flood, because every item containing the words in any arrangement qualifies. If a search returns zero, dropping to a single distinctive word is the fastest way to learn whether the file is findable at all. If a search returns hundreds, adding quotes narrows it more reliably than adding another word.

A related trap is searching for a string that the file never contained. Names remembered from a conversation, a subject line, or a ticket number are often not the name on disk, because the file was saved under whatever the exporting application chose. When a query fails, it is worth asking whether the typed string ever existed as text anywhere in or on that file. If the honest answer is that it might not, the query is the fault, and no repair to the index will produce a match.

Spelling deserves the same second of attention, particularly for names that mix languages or contain a client's name transliterated in more than one way. A file named after a person can exist under two spellings in the same folder, and the search only knows about the one that was typed.

Check where the search started

The second cheapest check is scope, which is invisible in the interface. The same string typed into two places searches two different sets.

Spotlight, opened with Command and Space, returns a mixture: apps, actions, mail, calendar entries, and files. A file can be present in the results and pushed below more prominent matches. Pressing Command and 2 switches to the files only browse mode, which removes that class of miss immediately.

A Finder window search has its own scope trap. By default, typing in the search field jumps the scope to the whole Mac, which discards the folder that was open. Finder Settings, under Advanced, contains a setting for what happens when performing a search, with an option to search the current folder instead. Changing it once removes a whole category of confusing results, because the search then matches the intention of having opened the folder first.

Saved searches carry an older scope with them too. A smart folder built months ago holds the criteria and the location it was created with, so it can keep returning an outdated set long after the work moved elsewhere. Opening it and reading the condition rows takes a moment and explains results that otherwise look stale.

Scope failures look like index failures from the outside. The file is returned when the scope is correct and absent when it is not, which reads as random behaviour until the setting is found.

Check the exclusions that were set once and forgotten

Exclusions are permanent, silent, and usually set months before the problem appears. There are two separate lists, and both are worth opening.

The first is the category list in System Settings under Spotlight, where unchecked result categories are simply left out of what gets shown. A category turned off during a cleanup of noisy results stays off.

The second is the search privacy list on the same settings page, which holds folders and disks excluded from indexing entirely. Anything inside them returns nothing, forever, with no error. Apple's guidance on preventing Spotlight searches in specific folders or disks also notes that a Time Machine backup disk keeps showing an indexing message when excluded, because that indexing is required for Time Machine itself.

Permissions act as a third kind of exclusion, and they look nothing like one. macOS gates several locations per application, so a tool that was refused access to a folder returns an empty result from it rather than an error. A search run from a terminal can hit the same wall, which is why a command that lists a folder fine in one context returns nothing in another. When a single application is the only one failing, permissions are the first place to look, not the index.

There is a fourth exclusion that is not a setting at all. A folder whose name ends in .noindex is skipped by the indexer, and the suffix survives duplication, so copying such a folder carries the behaviour along with it. Checking for it takes one look at the folder name.

Ask the volume whether it is indexed

If every query fails on one disk and works on another, the disk is the variable. Guessing is unnecessary, because the volume can be asked directly.

Running mdutil -s /Volumes/DiskName prints whether indexing is enabled for that volume in a single line. A volume reporting that indexing is disabled will never return results in anything built on the system index, no matter how the query is phrased. External drives and disks that were removed while busy are the common cases, and reformatted drives sometimes arrive with indexing off.

Network shares deserve separate treatment. Whether a share is searchable depends on the server rather than on the Mac, which is why a query that works on a local copy of a folder can fail on the mounted version of the same folder. That is not a fault to fix locally, and the practical response is to search the share with a tool that reads the filesystem directly.

The same command is worth running on the startup disk after an upgrade or a migration. A machine that has just restored from a backup spends a long stretch rebuilding its catalogue, and searches during that window return partial results that look like corruption.

Places the index was never going to reach

Some failures are not faults. The item was outside the catalogue by design, and no repair will change that.

Files inside a zip archive or a disk image are not visible until the archive is opened. The archive itself is indexed, its contents are not, and a search for a document that lives inside one returns nothing while the document sits there unopened.

Cloud storage adds a version of the same thing. A file kept in the cloud with only a placeholder on disk has no local data to read, so anything that depends on reading the bytes cannot match it until the file is downloaded.

Content matching has a format limit as well. A scanned PDF made of page images holds no text until optical character recognition has been run on it, so both the index and a direct content search return nothing for a word that is plainly visible on the page.

Text that looks identical can also differ underneath. The same Japanese filename can be stored with a precomposed character or with a base character plus a combining mark, and an exact match against the wrong form fails even though both render the same on screen. A file that refuses to match its full name but appears when a short fragment is typed is a strong sign of this. Case sensitivity is the plainer cousin: find -name "*invoice*" misses Invoice_2026.pdf, while -iname matches it.

Rebuilding the index is the last step

Rebuilding is genuinely the correct action in one situation: the volume is indexed, nothing is excluded, the file is in a reachable place, and results are still wrong or stale. At that point sudo mdutil -E / erases the index for the volume and starts it again.

Two things are worth knowing before running it. The rebuild takes a long time on a large disk, during which results stay incomplete and battery use goes up, so starting it before a working session is the wrong time. And it fixes staleness, not scope, so if the earlier checks were skipped the same failure returns after the wait.

While a rebuild is running, direct filesystem tools still work normally. find and grep do not consult the catalogue at all, so a search that has to happen during those hours is still possible through a different route.

It is also worth confirming the file exists before starting anything that long. A single find limited to a likely directory settles the question in seconds and separates two very different situations: a catalogue that lost track of a file that is still on disk, and a file that is genuinely gone and belongs in a restore from a backup instead. Running the rebuild first mixes those two cases together and delays the answer by hours.

If a rebuild completes and the same file is still missing, that result is informative rather than disappointing. A fresh catalogue that does not contain the item means the item was never eligible for it, which sends the investigation back to exclusions, to the format of the file, or to the place it is stored.

What to change first

Work the checks in order and stop at the first one that explains the symptom, because the ordering is by cost and the last step is measured in hours. Then look at how many separate windows one lookup actually crossed before the work resumed, since that count is usually the real cost rather than the search itself. Atriens is built around collapsing that crossing, and the reach and permission questions behind most of these failures are answered on the FAQ.