Troubleshooting

Work down this page in order. Each step rules out a whole class of cause, so stopping to read logs before checking that the services are even running usually costs time.

Is it linked?

An installed scanner that was never linked is inert by design: it runs, logs nothing interesting, and never appears in the platform.

sudo test -f /etc/optix/scanner-config.json && echo linked || echo "NOT linked"

If that file is missing, the link step did not complete. Re-run the link command from your scanner group - see Scanners.

If it exists, check it points where you expect:

sudo python3 -c "import json;d=json.load(open('/etc/optix/scanner-config.json'));print(d['base_url'], d['organization_id'], d['scanner_group_id'], d['mode'])"

Two things to look at in that output:

• base_url must be your own platform's API hostname. Each brand has its own, so a config copied from another deployment links to nothing.
• mode must be running. A scanner left in maintenance connects fine and deliberately takes no work, which looks identical to a broken scanner from the platform side.

scanner-cli -mode_running

Are the services up?

systemctl status --no-pager scanner-active-discovery scanner-client-completed-tasks scanner-client-new-tasks scanner-task-manager scanner-vm scanner-dast optix-sync-tests.timer

All six services plus the timer should be active (running). The two that matter most for "nothing is happening":

• scanner-client-new-tasks fetches work. Down means the scanner never receives anything.
• scanner-client-completed-tasks reports results. Down means scans run but results never arrive, which presents as tasks that start and never finish.

sudo systemctl restart scanner-client-new-tasks.service

Are the containers up?

docker ps

You should see two: redis and owaspZap.

redis carries every queue between the services, so if it is down nothing works, including scan types that have no obvious connection to it. Check it first.

owaspZap only affects DAST. If it is missing, network vulnerability scanning continues and only web application scans fail.

note

kali-linux and nmap are expected to be absent from docker ps. They sit behind the disable compose profile and are invoked on demand rather than run as services.

Restart everything:

docker compose -f /etc/optix/docker-compose-optix.yml restart

Or rebuild the containers from scratch:

docker compose -f /etc/optix/docker-compose-optix.yml down && docker compose -f /etc/optix/docker-compose-optix.yml up -d

Can it reach the platform?

The scanner needs outbound HTTPS to your API hostname and nothing inbound.

curl -sS -o /dev/null -w "%{http_code}\n" https://<your-api-hostname>/

Anything other than a response code means a network path problem rather than a scanner problem: check egress filtering, proxy configuration, and DNS resolution from the host itself.

Read the logs

Only once the above are clean. Follow the service that matches the symptom:

sudo journalctl -u scanner-client-new-tasks.service -f

sudo journalctl -u scanner-task-manager.service -f

sudo journalctl -u scanner-vm.service -f

sudo journalctl -u scanner-dast.service -f

For a container:

docker compose -f /etc/optix/docker-compose-optix.yml logs -f --tail 100 owaspZap

Common causes

Symptom	Usual cause
Scanner never appears in the platform	Not linked, or base_url points at another deployment
Appears but takes no work	mode is maintenance, or its group is assigned to no zone
Tasks start and never complete	scanner-client-completed-tasks is down
Everything fails at once	redis container is down
Only web application scans fail	owaspZap container is down or out of memory
Vulnerability results look stale	optix-sync-tests.timer disabled, or the license key is missing or invalid

For the last one:

sudo systemctl status --no-pager optix-sync-tests.timer && sudo ls -la /etc/optix/license.key

sudo /usr/local/bin/sync-vulnerability-tests.sh

Still stuck

Collect the service states, the container list, and the last few hundred log lines from the failing service before opening a ticket - it is almost always the first thing asked for:

systemctl status --no-pager 'scanner-*' > /tmp/scanner-state.txt; docker ps -a >> /tmp/scanner-state.txt; journalctl -u scanner-client-new-tasks.service -n 300 --no-pager >> /tmp/scanner-state.txt

Then contact [email protected] with /tmp/scanner-state.txt attached.