Troubleshooting — macOS (Task Worker)

Overview

On macOS, Diskover runs only the Task Worker (diskoverd). The full Diskover stack (Elasticsearch, nginx, diskover-admin, diskover-web) must be running on a separate Linux host that this Mac worker connects to.

This page covers the 2.6.0+ installer layout (Python 3.13 venv, configure-worker.sh). On 2.4.x–2.5.x installs, the Python path is /usr/local/bin/python3.11, there is no configure-worker.sh, and configuration is manual (edit apiUrl in config.yaml).

Installation Paths

Service Management

New in Diskover v2.6.0 is the installed /opt/diskover/configure-worker.sh toolbelt, which can be used to issue Start/Stop/Restart/Status/Log commands directly to the installed Diskoverd and Celery services.

sudo /opt/diskover/configure-worker.sh status   [worker|celery|all]
sudo /opt/diskover/configure-worker.sh start    [worker|celery|all]
sudo /opt/diskover/configure-worker.sh stop     [worker|celery|all]
sudo /opt/diskover/configure-worker.sh restart  [worker|celery|all]
sudo /opt/diskover/configure-worker.sh logs     [worker|celery] [-f]

Raw launchctl equivalents:

# Start
sudo launchctl load /Library/LaunchDaemons/com.diskoverdata.diskoverd.plist

# Stop
sudo launchctl unload /Library/LaunchDaemons/com.diskoverdata.diskoverd.plist

# Check status
sudo launchctl list | grep diskover

A PID value in the output confirms the service is running. A - in the PID column means it is not running.

Celery gotcha: the celery plist's launchd label is com.diskover.celery but its filename is com.diskoverdata.celery-worker.plist. Label-based commands (launchctl bootout system/com.diskover.celery) and path-based ones (load/unload on the plist path) differ accordingly — or just use the provided configure-worker.sh, which handles it.

Log Locations

# Tail service startup logs
sudo tail -f /opt/diskover/logs/diskoverd.std*

# Tail crawl subprocess log (replace with your worker name)
sudo tail -f /opt/diskover/logs/diskoverd_subproc_<workername>.log

Start with stdout and stderr for service-level issues. Switch to the subprocess log for task-specific failures.

Post-Install Configuration

On 2.6.0+ the installer's setup dialogs collect the server address, API user/password, and internal API key, verify them live against the server, write the config, and start the service.

Leverage the provided configure-worker.sh script to (re)configure the worker afterwards, or after a headless install:

sudo /opt/diskover/configure-worker.sh                 # interactive
sudo /opt/diskover/configure-worker.sh --server https://<diskover-web-host>:8000 \
     --api-user <user> --api-pass <pass> --api-key <internal-api-key>
sudo /opt/diskover/configure-worker.sh check           # test current creds
sudo /opt/diskover/configure-worker.sh config          # edit config.yaml directly (syncs user copy)

The Mac must be able to reach the Diskover Web host on port 8000 (or 443 with SSL).

Configure the Worker in Diskover Admin

Once the service has started and the worker appears in the UI:

1. Navigate to Diskover Admin > Configuration > DiskoverD

2. Click on your Mac's hostname

3. Review the following:

   • Log To File: enabled

   • Log Directory: /opt/diskover/logs/

   • Python Location: pre-set by the installer to the virtual environment path /opt/python-venv-diskover/bin/python3

   • Timezone: set to your local timezone

4. Save

Troubleshooting

Worker Not Appearing in Diskover Admin

The service started but the worker is not showing in Diskover Admin > Configuration > DiskoverD.

Check the service is actually running:

sudo launchctl list | grep diskover

Check for connection errors in the logs:

sudo tail -50 /opt/diskover/logs/diskoverd.stdout.log
sudo tail -50 /opt/diskover/logs/diskoverd.stderr.log

Check the stored credentials:

sudo /opt/diskover/configure-worker.sh check

Common causes:

• apiUrl points at the wrong host — re-run sudo /opt/diskover/configure-worker.sh

• Wrong API user/password or internal API key — check will tell you; reconfigure with corrected values

• Port 8000 is blocked between this Mac and the Diskover Web host — test with:

  curl -s http://<diskover-web-host>:8000/api.php

• The Diskover Web/Admin service on the host is not running

Worker Registered Under the Wrong Name

The worker name is derived from the Mac's hostname at install time and written into the LaunchDaemon plist. If the hostname has changed or the name is unexpected:

# Check what name the plist is using
cat /Library/LaunchDaemons/com.diskoverdata.diskoverd.plist | grep -A2 "\-n"

To change it, edit the plist and update the -n argument, then reload the service.

Note: Worker names cannot contain spaces or special characters. The installer sanitizes the hostname by replacing special characters with hyphens.

Task Fails Immediately

The worker accepted the task but the crawl process exited without completing.

Check the subprocess log:

sudo tail -100 /opt/diskover/logs/diskoverd_subproc_<workername>.log

For more detail, increase the log level to DEBUG in Diskover Admin > Configuration > DiskoverD, then retry the task.

Common causes:

• Path being scanned does not exist or is not accessible by root

• macOS privacy protection (TCC): scanning Desktop/Documents/Downloads requires granting Full Disk Access to /opt/python-venv-diskover/bin/python3 under System Settings → Privacy & Security

• Elasticsearch unreachable from this Mac — test: curl -s http://<es-host>:9200/_cluster/health

• Python path misconfigured in Admin UI — verify /opt/python-venv-diskover/bin/python3 --version runs successfully

External Command Not Found (e.g. mediainfo, ffmpeg)

Plugins or scanners that shell out to external tools (such as mediainfo, ffmpeg, or others installed via Homebrew) may fail with an error like:

CRITICAL - mediainfo command not found in path! (Exit code: 1)

On 2.6.0+ the LaunchDaemon ships with an active EnvironmentVariables block whose PATH already includes /opt/homebrew/bin and /usr/local/bin, so Homebrew tools are found out of the box. If a tool lives in a non-standard location, append its directory to the PATH string in the plist:

sudo -i
vi /Library/LaunchDaemons/com.diskoverdata.diskoverd.plist

<key>EnvironmentVariables</key>
<dict>
    <key>PATH</key>
    <string>/opt/python-venv-diskover/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
    <key>DISKOVER_INTERNAL_API_KEY</key>
    <string>…</string>
</dict>

Warning: do not remove the DISKOVER_INTERNAL_API_KEY entry from this block — it is how the worker authenticates to the admin API.

Save the file, then reload the service for the change to take effect:

sudo launchctl unload /Library/LaunchDaemons/com.diskoverdata.diskoverd.plist
sudo launchctl load /Library/LaunchDaemons/com.diskoverdata.diskoverd.plist

Note: This PATH applies to all subprocesses spawned by the Task Worker, not just the plugin that triggered the error.

Connecting to a Single-Stack OVA

If the Diskover stack is running on a single OVA, the DiskoverD configuration for the Elasticsearch connection is likely set to localhost. This must be changed to the OVA's IPv4 address so the Mac Task Worker can fetch the ES configuration and connect properly.

Navigate to Diskover Admin > Configuration > DiskoverD and update the Elasticsearch host from localhost to the OVA's IP.

Running a Manual Scan

To test indexing without going through the task queue:

sudo /opt/diskover/configure-worker.sh run -i diskover-<indexname> /path/to/scan

or directly (the internal API key is auto-backfilled from the LaunchDaemon plist for manual runs, and the config mirror means non-root runs see the same settings):

sudo /opt/python-venv-diskover/bin/python3 /opt/diskover/diskover.py -i diskover-<indexname> /path/to/scan

To export the key into your current shell for repeated manual work:

eval "$(sudo /opt/diskover/configure-worker.sh env)"

Note: All index names must start with diskover-.

Reinstalling Python Dependencies

If the Task Worker fails to start with ModuleNotFoundError or similar import errors, reinstalling the Python dependencies can resolve the issue.

On 2.6.0+ Diskover runs from the virtualenv at /opt/python-venv-diskover:

sudo /opt/python-venv-diskover/bin/python3 -m pip install -r /opt/diskover/requirements.txt

After reinstalling, restart the service:

sudo /opt/diskover/configure-worker.sh restart worker

Note: a reinstall/upgrade of the DMG recreates the venv from scratch (with the bundled offline wheels), which is usually the cleaner fix for a broken environment.

Reinstalling / Upgrading

Reinstalling over an existing installation keeps your existing config.yaml and pre-fills the setup dialogs from the previous install; the venv is recreated clean, so stale packages never carry over. If you need a fresh config:

sudo rm /var/root/.config/diskoverd/config.yaml

Then reinstall, or re-run configuration:

sudo /opt/diskover/configure-worker.sh