Skip to content

Troubleshooting Your NodeZero® Runner

Common Issues and Fixes

Encountering issues with your NodeZero Runner can disrupt your internal pentesting workflow. This page provides step-by-step solutions to common problems, such as connectivity failures, Docker permission errors, and systemd configuration issues. Whether your Runner isn’t connecting, failing deployments, or encountering log errors, these troubleshooting steps will help you restore functionality and keep your scheduled pentests running smoothly.

Runner not connecting:

Diagnose and resolve issues when your Runner fails to connect to the Horizon3.ai API.

Check the last heartbeat: 

h3 runners
If last_heartbeat_at is over 60 seconds old, the Runner may have stopped or lost connectivity.

Verify the process is running: 

h3 ps-runner
Inspect logs for errors: 
h3 tail-runner my-nodezero-runner

Recent commands:

Review the most recent commands executed by your Runner to identify potential errors or failures.

View the last 5 commands executed by the Runner: 

h3 runner-commands my-nodezero-runner
Look for non-zero exit statuses or error messages.

Docker permission errors:

Address permission issues that prevent the Runner from accessing Docker on your NodeZero Host.

If you see an error like: 

[!] FAILED: Failed to validate Docker. Verify this account has permissions to run Docker and retry.
Run the Runner with sudo: 
sudo h3 start-runner my-nodezero-runner /tmp/my-nodezero-runner.log
Or add the user to the docker group (e.g., for user ubuntu): 
sudo usermod -aG docker ubuntu
sudo systemctl restart docker
Log out and back in to apply group changes.

Retry a failed deployment:

Retry a NodeZero deployment that failed due to temporary issues with your Runner.

Queue a new NodeZero deployment to retry a failed attempt: 

h3 run-nodezero-on-runner {op_id} my-nodezero-runner

Find the op_id of the latest pentest:

h3 pentest

For further assistance, contact support@horizon3.ai.

Troubleshoot systemd:

Resolve issues related to the systemd service configuration for auto-starting your Runner.

209/STDOUT Error: If systemd can’t write to the log file (e.g., /tmp/my-nodezero-runner.log), adjust permissions:

chmod 666 /tmp/my-nodezero-runner.log
Or delete it to let systemd recreate it.

Resources:

For systems not using systemd, contact support@horizon3.ai for assistance.


schedule NodeZero Runner chevron_right
home Portal home chevron_right