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.

Installation Paths

Service Management

The Task Worker runs as a macOS LaunchDaemon. All service commands must be run as root:

# 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 diskoverdata

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

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/log/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

After installation, two configuration steps are required before the worker will function:

1. Set the Diskover Web URL

Edit the worker config as root:

sudo -i
vi /var/root/.config/diskoverd/config.yaml

On line 33, update apiUrl to point to your Diskover Web host:

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

Save and exit. The Mac machine must be able to reach the Diskover Web host on port 8000.

2. 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. Set the following:

   • Log To File: enabled

   • Log Directory: /opt/diskover/log/

   • Python Location: /usr/local/bin/python3.11

   • 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 diskoverdata

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

Common causes:

• apiUrl in config.yaml is still set to localhost — update it to the Diskover Web host IP

• 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/log/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

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

• Python path misconfigured in Admin UI — verify /usr/local/bin/python3.11 --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)

This happens because the LaunchDaemon runs with a minimal PATH that does not include Homebrew directories (/opt/homebrew/bin) or other non-standard locations. The tool is installed on the machine but the service cannot find it.

Fix: uncomment the EnvironmentVariables block in the plist

Edit the LaunchDaemon plist as root:

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

Find the commented-out EnvironmentVariables block and uncomment it:

<key>EnvironmentVariables</key>
<dict>
    <key>PATH</key>
    <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
</dict>

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

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

If the tool is installed in a non-standard path not listed above, append it to the PATH string before reloading.

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 -i
python3.11 /opt/diskover/diskover.py -i diskover-<indexname> /path/to/scan

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. This is also required after a Diskover upgrade that introduces new package requirements.

On macOS, Diskover uses the system Python 3.11 installed at /usr/local/bin/python3.11:

sudo /usr/local/bin/python3.11 -m pip install -r /opt/diskover/requirements.txt

After reinstalling, reload the service:

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

Reinstalling / Upgrading

If reinstalling over an existing installation, the postinstall script will skip overwriting an existing config.yaml. If you need a fresh config:

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

Then reinstall or manually copy from the sample:

sudo cp /opt/diskover/configs_sample/diskoverd/config.yaml /var/root/.config/diskoverd/config.yaml