Troubleshooting

Fixes for installation warnings, an engine that won't start, slow or stuck reading, agent connection problems, failed files and exports, plus where the logs are and how to run discovery doctor.

#Start here: the system check

Most problems show up in the app's own health check:

• In the app: Settings → This computer → System check → Run check.
• In a terminal: discovery doctor.

Each check gets a green or red dot. A failed one says what to do. The checks include Python, the app data folder, the database extensions, the OCR engine, and each model (name detection, speech recognition, search by meaning).

discovery doctor

If the discovery command isn't installed, run the same check through the app's bundled Python:

"/Applications/Discovery Engine.app/Contents/Resources/engine/python/bin/python3" -I -B -m discovery_engine doctor

& "$env:LOCALAPPDATA\Discovery Engine\engine\python\python.exe" -I -B -m discovery_engine doctor

A model reported as not downloaded yet isn't an error: download it from Progress or Settings.

#Installing

#Mac: "cannot verify" / the app won't open

The app isn't signed with an Apple Developer ID yet. Open System Settings → Privacy & Security, scroll down, click Open Anyway next to the Discovery Engine message, and confirm. Needed once per installation. See Installing on Mac.

#Mac: the app refuses to open on an older Mac

The app needs macOS 14 or later on Apple Silicon.

#Windows: "Windows protected your PC"

Click More info, then Run anyway. If there's no Run anyway, right-click the installer → Properties → tick Unblock → OK, then run it again. A PC managed by IT may need them to allow it.

#Windows: the first start is slow

The very first start can take up to a minute while Microsoft Defender scans the app's files.

#The app

#"Engine starting…" never finishes, or the engine did not start

1. Wait a minute (on Windows, Defender's first scan).
2. Quit the app completely and open it again.
3. If it still fails, look at the engine log (below). It records why the engine stopped.

The bottom of the left column shows the engine's state: Engine 0.1.0 (running), Engine starting…, or Engine not answering.

#"Live updates paused… Reconnecting…" / "Engine access refused"

The first fixes itself. For the second, restart the app.

#Reading

#Reading seems stuck

1. Look at Progress → Reading now: is Files done moving at all?
2. Check the activity log is on (Settings → This computer → Activity log; Normal is the default), and open it (Show in Finder/Explorer), or ask your agent "How is reading going?" The agent runs discovery log show.
3. Look for a heartbeat line in the last minute or two. It lists each file being read and for how long.
   • Recent heartbeat: the app is working. One huge scanned PDF or a long recording can take an hour or more on a slow computer; the log shows OCR progress page by page.
   • No heartbeat for several minutes during a run: the engine is stuck. Quit and reopen the app. Finished work is kept, and Resume carries on.

discovery log show --lines 80
discovery log show --grep failed

#Recordings (or other files) are waiting

Progress says what they wait for, such as Recordings wait for the speech model. Click the button beside it (Download the speech model). Reading picks them up once it's installed.

#Reading is slow

• Click Estimate reading time to see which kinds of file take the time. Scanned pages usually dominate.
• Close other heavy programs: each reading process needs about 2.5 GB of memory.
• Keep a laptop plugged in. The app keeps the computer awake while reading, but a closed lid or a dead battery still stops it.

#Files failed

See the Failures section of Progress. Each row says what happened. Fix the cause (close a program that has the file open, free disk space, reconnect a drive), then click Retry or Retry all N. A reading process stopped, often from lack of memory usually means the computer ran short of memory on a large file: close other programs and retry.

#"This case's folder is not where it was"

The folder was moved, renamed or is on a disconnected drive. Click Find the folder and choose its new location, or reconnect the drive and rescan.

#Your AI agent

#The agent says discovery isn't found

• On Start Up, click Install command-line tool (or Update command-line tool).
• Copy a fresh prompt. If the tool isn't on the PATH, the prompt gives the agent the full path.
• On a Mac, agent apps opened before you clicked Add to PATH won't see the change: restart the agent app, or just rely on the full path in the prompt.
• Make sure the agent app is allowed to run commands on your computer.

#"The command-line tool needs updating"

It points at another copy of the app or another data folder, typically after an update. Click Update command-line tool on Start Up.

#The agent says the engine is unavailable (exit code 7)

Open Discovery Engine and leave it running, then ask the agent to try again.

#Every agent command is refused (exit code 4)

Agent access is off for that case. Turn on Settings → This case → Let AI agents use this case.

#"The prompt is withheld"

One of your chosen folders has a name the app found in the case files (a person's name, say). Choose differently named agent work and export folders on Start Up.

#Nothing appears in the Agent log

The agent hasn't run a discovery command yet. Check it received the prompt, that the tool is installed, and that it may run commands.

#Exports

• Nothing to export: only documents with approved highlights are exported. Review proposals on the Highlights screen first.
• "It cannot be inside the case's own folder": choose an export folder outside the case's folders.
• Documents left out: each has a reason. See Exports → Left out.
• "Its PDF could not be written": close the file if it's open in another program, then export again.

#Moving a case

• "That drive is formatted as FAT32": use a drive formatted as exFAT; FAT32 can't hold files of 4 GB or more.
• "Not enough space there": free space on the drive or pick another.
• Files missing after import: check you chose the right folder of originals under Where are the original documents now? The count tells you how many were found.

#Where the logs are

discovery log path prints the activity log's location.

#Still stuck?

Gather a screenshot of the window, the output of discovery doctor (or the System check), and the engine log, and send them to whoever supports your installation.