Troubleshooting
Start with macx doctor. It checks the app, the engine, the CLI and the system integrations in one go.
Run macx doctor
macx doctor
Each line is a check: ✓ fine, ! worth a look, ✗ a problem, · for information. It exits with code 1 if anything failed (macx doctor --json gives the same results as data).
| Check | What it looks at | If it fails |
|---|---|---|
| app | Mac Explorer is installed, and which version | Re-run the install command |
| version | Whether a newer release exists | macx update |
| bun | Bun is installed (it runs search and indexing) | curl -fsSL https://bun.sh/install | bash, then reopen the app |
| cli | macx is on your PATH | Add ~/.local/bin to your PATH |
| index server | The engine is running and answering | Open the app, or check macx service status |
| token | The CLI can authenticate to the engine | Restart the app so it writes a fresh token |
| engine | Phase (loading, ready, busy) and the running job | Wait for a big job to finish, or see below |
| lag | Whether the engine is responding promptly | A heavy job may be running. See macx engine status |
| api | The CLI and the engine speak the same version | macx update |
| login item | The login item exists and points at the installed app | macx service install |
| links | macexplorer:// links open Mac Explorer | Reinstall, or open the app once |
| markdown | Whether Markdown opens in Mac Explorer (optional) | macx defaults set --markdown if you want it |
| quick actions | Finder’s Open in Mac Explorer and Go to Path are installed | macx quick-actions install |
| reveal | Where Reveal in Finder goes (optional) | macx defaults set --file-viewer if you want it |
Search finds nothing, or misses a folder
- Is the folder indexed? Search only covers indexed locations. Check Settings ▸ Search Index, or run
macx status. Add a folder with Add folder…, or press ⌘I inside the ⌘K palette to index the folder you’re in. - Is it still indexing? The index chip in the status bar and
macx engine statusshow progress. - Is it a build or dependency folder?
node_modules,.git,dist,buildand similar folders are deliberately kept out of results. See the three tiers. - Are you searching for words inside a file? Search matches names, not contents.
Search says the engine isn’t running
The engine restarts itself if it stops responding. If it keeps failing:
- Open Settings ▸ Search Index and click Retry engine.
- Run
macx doctorand check the bun and index server lines. - Click Copy diagnostics, or Send report under Settings ▸ Appearance ▸ Diagnostics & Logs.
Folder sizes look too small
- The Total column only counts what’s indexed. Folders outside your indexed locations show no total. Use Disk Usage for those.
- A location that was indexed before an update may show estimates until it’s re-indexed. Use the re-index button next to it in Settings ▸ Search Index.
Disk Usage shows unreadable folders
macOS protects some folders, such as Mail, Safari and other apps’ data. Click Open Full Disk Access on the banner, turn Mac Explorer on, and click Measure now.
The app won’t open
This build isn’t notarized yet. The installer handles Gatekeeper for you. If you installed manually, right-click the app in /Applications and choose Open the first time, or re-run the install command.
Reveal in Finder opens the wrong app
If you turned on --file-viewer and want Finder back:
macx defaults restore
Holding ⌥ while revealing always goes to Finder.
Still stuck?
Run macx doctor --json, then send the output and the app version (bottom of the Settings sidebar) along with a diagnostic report from Settings ▸ Appearance ▸ Diagnostics & Logs.