Fixing Spotlight When It Stops Finding Files You Know Exist

You search for a file you know exists — you can see it right there in Finder — and Spotlight returns nothing. This almost always means the index itself is stale, disabled for that volume, or partially corrupted, rather than anything wrong with the file itself.

Step 1: check whether indexing is actually enabled for that volume

mdutil -s /
mdutil -s /Volumes/ExternalDrive

If this reports indexing as disabled for the relevant volume, that alone explains empty search results — no amount of waiting will fix it until indexing is turned back on.

sudo mdutil -i on /Volumes/ExternalDrive

Step 2: check if mds/mdworker is actually running

ps aux | grep -E "mds|mdworker"

If these core Spotlight processes aren’t running at all, or one is stuck consuming enormous CPU/memory without progress, that points to indexing being stuck rather than simply behind — worth a reboot before more invasive steps, since a stuck mds process can sometimes just need to be restarted.

Step 3: check if a specific file’s metadata even got extracted

mdls ~/Documents/report.pdf

If mdls returns essentially empty output for a file that should have rich metadata, its content was never successfully processed by an importer — worth checking mdimport -d2 filename for more verbose diagnostic output about exactly why:

mdimport -d2 ~/Documents/report.pdf

Step 4: force a clean rebuild for the affected volume

If indexing is enabled and running but results still seem wrong or incomplete, the most reliable fix is discarding the existing index and rebuilding from scratch:

sudo mdutil -E /

This erases and triggers a full reindex of the specified volume — safe (it doesn’t touch your actual files, only Spotlight’s separate index of them), but can take a meaningful amount of time on a large volume, during which search results will be incomplete until the reindex finishes.

Step 5: check indexing progress

mdutil -s /

Repeated checks of this command show whether indexing is actively progressing (it reports differently while a reindex is in flight) — useful for confirming the rebuild triggered in step 4 is actually making progress rather than stuck.

Step 6: check Spotlight’s privacy exclusion list

If a specific folder consistently doesn’t show up in results, confirm it isn’t explicitly excluded via System Settings → Siri & Spotlight → Spotlight Privacy — a folder added there (deliberately or accidentally) is fully excluded from indexing regardless of any of the steps above.

Why this happens more often after certain operations

Spotlight indexing issues most commonly follow a migration from another Mac, restoring from a Time Machine backup, or an external drive that was indexed on a different Mac and then connected to this one — situations where the on-disk index metadata doesn’t necessarily match what the current system expects, making a clean mdutil -E rebuild the most reliable fix rather than trying to repair a possibly-inconsistent existing index in place.

Step 7: check for a hidden, deliberate exclusion marker file

find ~ -name ".metadata_never_index"

Beyond the GUI-based Spotlight Privacy list, macOS also honors a .metadata_never_index marker file placed directly inside any folder — a mechanism some developer tools and version control systems create automatically to keep their own working directories out of the index, and one that’s easy to forget exists since it’s invisible in Finder and doesn’t appear in the Spotlight Privacy settings pane at all. A folder that seems inexplicably un-indexed despite mdutil -s reporting indexing enabled for the whole volume is worth checking specifically for this marker before assuming something more complicated is wrong.

Step 8: check whether a specific file type’s importer is the actual gap

mdimport -L

Spotlight relies on importer plugins (.mdimporter bundles) to extract searchable metadata from each specific file type — PDF text, image EXIF data, source code symbols. mdimport -L lists every importer currently registered on the system; if searches consistently fail for one particular file type specifically (while working normally for everything else), a missing, outdated, or crashing importer for that format — rather than a general indexing problem — is the more precise diagnosis, and checking whether the application that creates that file type ships and correctly registers its own importer is the relevant next step.

Related:

Sources: