Spotlight is macOS's system search index. It covers filenames, metadata, Mail, Calendar, and document content. A missing file may never have entered the index, or an exclusion, permission boundary, or importer may be hiding it.

First, identify what is missing

Confirm the file exists, then test the filename layer in Terminal:

mdfind -name "quarterly-report"

If mdfind -name finds it, the filename is indexed; a missing content hit points to content the importer could not read, such as a scanned PDF without text, or image text Live Text has not recognized. Test with mdfind "renewal clause".

If it is missing too, check whether the item is indexed. mdls /path/to/file prints metadata; null kMDItemFSName or core fields usually mean it is out of scope. mdutil -sa shows all volumes, including the APFS Data volume. mdfind and NSMetadataQuery query the same index, subject to importers and exclusions.

If mdfind finds the file but the Spotlight UI does not, check result categories under System Settings → Spotlight → Search results, then Finder search scope and filters, before rebuilding.

Seven common causes

  1. Privacy exclusions: the folder is in Spotlight Privacy, so it is skipped with its descendants.
  2. Folder names ending in .noindex: excluded; .metadata_never_index at a volume root excludes the whole volume.
  3. Disabled or damaged index: off, corrupt, or stuck; the APFS Data volume can be disabled separately.
  4. External or network drives: excluded, still indexing, or not indexed locally.
  5. Protected system folders: excluded by design or by TCC.
  6. Permissions: your account cannot read the folder, or TCC protects it.
  7. Recently written files: indexing can lag by seconds.

Fixes, one by one

1. Privacy exclusions

Open System Settings → Spotlight → Search Privacy (macOS 26/27); macOS 13–15 uses Siri & Spotlight → Spotlight Privacy; macOS 12 and earlier uses Spotlight → Privacy. Remove the folder, then rebuild as in fix 3 if needed.

2. Folder names ending in .noindex

Spotlight skips a folder whose name ends in .noindex, including its descendants; .metadata_never_index at a volume root skips the whole volume. Find candidates with find ~/Documents -type d -name '*.noindex' or ls -d ~/Documents/*.noindex. Rename the folder to drop the suffix; do not look for a marker file. A volume-root marker may need sudo rm /Volumes/ExternalDrive/.metadata_never_index, then sudo mdutil -E /Volumes/ExternalDrive. .noindex is not honored on the mount point itself, and re-indexing deliberately excluded NVR, VM, or media folders can cause heavy load or instability.

3. Disabled or damaged index

Run mdutil -sa to see all volumes; mdutil -s / may report only /, while the APFS /System/Volumes/Data volume is indexed separately. Check it with sudo mdutil -s /System/Volumes/Data; if disabled, use sudo mdutil -i on /System/Volumes/Data, then sudo mdutil -E /System/Volumes/Data. sudo mdutil -Ea rebuilds every volume and takes longer. Rebuilding regenerates only the index, not your files, and runs in the background.

4. External and network drives

Confirm an external volume is not in Spotlight Privacy, then use sudo mdutil -s /Volumes/DriveName and rebuild it if needed. SMB and AFP shares usually are not fully indexed locally, so search depends on the server; Finder or NAS search is more reliable. macEverything itself scans only your home folder and /Applications, and does not support external or network drives.

5. Protected system folders

Some system locations and app data containers are excluded by design or by TCC. SIP protects system files from modification, not arbitrary files from Spotlight, so do not disable it. Use Finder's Go to Folder (⇧⌘G) or Terminal; read access still depends on permissions.

6. Permissions

If ls -ld /path shows no read or execute permission, Spotlight and mdfind may not see the contents. Fix access in Finder's Get Info → Sharing & Permissions. Terminal and third-party tools may need Full Disk Access. For macEverything it is optional: without it, the results window status bar shows a gap count; open it to see the folders. After granting access, restart the engine (macEverything stop && macEverything start) so the index can add those locations. The CLI must be installed and on your PATH, or use the bundled Contents/MacOS/macEverything.

7. Recently written files

Indexing is asynchronous; wait a few seconds after saving. To request an import and inspect metadata:

mdimport ~/Documents/report.pdf
mdls -name kMDItemFSName -name kMDItemContentType ~/Documents/report.pdf

If it is still unindexed, revisit exclusions, volume status, and permissions. Network mounts, excluded directories, and temporary files deleted or renamed immediately may never be indexed.

Spotlight vs filename search

Spotlight is strongest on content and metadata: Mail, Calendar, Notes, settings, and body text. macEverything itself searches filenames only: it keeps a local index of your home folder and /Applications, excludes ~/Library, node_modules, and .git, and follows changes with FSEvents.

On an Apple M5 test set of about 1.28 million entries, the first scan of one million files takes 1.0–1.6 seconds, P99 query latency is 2.9–3.6 ms, and changes are searchable within 0.3 seconds. The UI uses about 136 MB. Wildcards, paths, and whole words are supported; regular expressions are not, and external or network drives are not indexed.

Use macEverything for filenames and Spotlight for phrases inside files. Separate indexes mean no conflict.