How to Use the mddiagnose Command in macOS Terminal to Generate Comprehensive Spotlight Diagnostic Dumps

Spotlight is central to the macOS experience, powering everything from instant app launches and file queries to Mail search and Siri suggestions. However, after major macOS upgrades or mass file migrations, users occasionally encounter indexing loops: the mds and mds_stores background processes consume 100% CPU for days, searches return missing files, or Spotlight progress bars stall indefinitely.

While rebuilding the index using mdutil -E / is a common first aid step, it does not explain why the indexing failure occurred—such as a corrupt PDF metadata importer or an unreadable external drive partition. To obtain forensic diagnostic telemetry, Apple includes a dedicated command-line utility: mddiagnose. This guide explains how to generate, analyse, and troubleshoot Spotlight diagnostic reports in macOS.

What mddiagnose Collects

The mddiagnose utility captures a comprehensive snapshot of the entire macOS metadata indexing subsystem:

• Active Importer States: Details which Spotlight importer plugins (MDImporters) are currently parsing files.
• File System Metadata: Dumps volume flags, Spotlight store permissions, and exclusion lists.
• Crash Logs and Faults: Gathers recent crash backtraces from mds, mdworker, and related daemons.
• Extended Attributes: Analyzes quarantine tags and FileProvider metadata.

Step-by-Step Diagnostic Execution

1. Launch Terminal with Administrative Privileges

Open Terminal from /Applications/Utilities/. Because Spotlight maintains root-level database stores, run mddiagnose with sudo:

sudo mddiagnose

2. Monitoring the Collection Process

The diagnostic routine executes across multiple stages, printing progress indicators:

Generating diagnostic report...
Capturing metadata configuration...
Gathering Spotlight volume status...
Collecting unified logs for subsystem com.apple.spotlight...
Compressing diagnostics into /var/tmp/mddiagnose_YYYY.MM.DD_HH-MM-SS.tar.gz

The process typically takes 60 to 120 seconds. Once finished, mddiagnose saves a compressed tarball in /var/tmp/.

3. Exporting to a Convenient Location

To write the diagnostic archive directly to your Desktop for easy inspection, specify the -f directory flag:

sudo mddiagnose -f ~/Desktop

Targeted Flags for Faster Diagnosis

Command Syntax	Execution Scope	Primary Benefit
sudo mddiagnose -m	Metadata configuration and store status only (omits unified logs)	Generates in under 10 seconds; minimal disk footprint.
sudo mddiagnose -w	Focuses specifically on mdworker process activity	Identifies crashing file parser plugins immediately.
sudo mddiagnose -s	Spotlight server state dump	Pinpoints hung query dispatch threads.

Identifying Culprit Files and Crashing Importers

Extract the generated tarball and inspect mds.log and importers.txt:

• Corrupt File Identification: Look for repeated lines indicating mdworker failed on path /Users/.../broken_file.ext. This pinpoints the exact file triggering indexer crashes.
• Third-Party Importer Crashes: Check if a legacy audio plugin or CAD importer in /Library/Spotlight/ is crashing mdworker. Remove obsolete plugins to restore indexing performance.