Skip to content

Common Setup Issues

This section offers solutions to common installation, configuration, and operational issues encountered with NodeZero. Whether you’re dealing with connectivity problems, container runtime permission errors, or disk space limitations, you’ll find guidance here to help you quickly troubleshoot and resolve these issues. For additional support, feel free to contact our Support Team.

Host cannot connect to the Portal

Your NodeZero Host fails to communicate with the Portal, showing errors like Unable to connect or Connection timed out, or warnings like Attempted 1 Ping to <resource>: FAILED.

Verify firewall settings

Ensure that your firewall is not blocking outbound connectivity to the required domains.

Whitelist for domains and ports

Whitelist requirements differ depending on whether you're using the Preconfigured OVA or performing a Manual Installation.

DNS filtering

Confirm that DNS filtering is not redirecting or blocking the whitelisted domains. Even if the domains are whitelisted in the firewall, DNS rules can still block them, preventing successful outbound connectivity.

Test connectivity

US Region

  ping portal.horizon3ai.com

  curl -I https://portal.horizon3ai.com

EU Region

  ping portal.horizon3ai.eu

  curl -I https://portal.horizon3ai.eu

Check network reachability

Ensure that your network allows outbound access to the internet.

  • If using VLANs, verify that VLAN tagging is not blocking access to external domains.
  • Confirm that your NodeZero Host has a valid route to the required domains.

Incorrect IP configuration

The NodeZero Host may fail to communicate with other devices or the internet due to misconfigured IP settings, such as an incorrect IP address, default gateway, or DNS.

Verify IP settings

Check if the IP address, default gateway, and DNS settings were correctly configured during setup.

  • Review the initial configuration values entered for the VM.
  • Confirm the assigned IP address using: 
    ip addr

Configure a static IP address

By default, the NodeZero Host uses DHCP. To set a static IP, use the built-in Host Utility.

  1. Open a terminal and run the n0 command.
  2. Select option 3 to configure a static IP.

  3. Follow the prompts to enter:

    • IP Address: The static IP for the host (e.g., 192.168.1.100).
    • Subnet Mask: (e.g.255.255.255.0).
    • Gateway: Your network’s gateway IP (e.g., 192.168.1.1).
    • DNS Nameserver: Primary and secondary DNS servers (e.g., 8.8.8.8, 8.8.4.4).

  4. Verify the new IP configuration: 

    ip addr show
  5. Test connectivity with the new static IP: 
    ping <static-ip>
  6. If changes don’t apply immediately, reboot the host: 
    sudo reboot
  7. To revert to DHCP, rerun the n0 utility, select option 3, and choose the DHCP toggle.

Container runtime permission issues

Proper container runtime configuration and user permissions are essential for NodeZero to function correctly. Many users encounter issues related to Docker or Podman validation, permissions, and access restrictions. These problems typically arise due to incorrect user permissions, missing group memberships, or insufficient sudo privileges.

"Failed to validate your container runtime" error

The NodeZero Launch Script detects your container runtime and reports a corresponding error. The text after the runtime name tells you the cause. Select your runtime below for the message you'll see and the most common causes and fixes.

[!] FAILED: Failed to validate Docker. ...

Permissions to run Docker (Verify this account has permissions to run docker)

The user running NodeZero is not in the docker group. Add them, then log out and back in (or reboot) for the change to take effect:

sudo usermod -aG docker $(whoami)
groups $(whoami)   # confirm "docker" is listed

Docker daemon not started (Verify the docker daemon/service is started)

sudo systemctl start docker

Docker not installed (Verify that docker is installed)

Install a container runtime — see Container Runtime Installation.

Volume-mount path error (The path ... is not shared and is not known to docker)

This typically occurs on Docker Desktop (macOS/Windows), where directories must be explicitly shared with the runtime. Run NodeZero from a directory Docker is allowed to mount. The error output includes a link to the relevant file-sharing documentation for your platform (Docker for Mac, Docker for Windows).

[!] FAILED: Failed to validate Podman. ...

When using Podman, NodeZero always runs containers with sudo.

Permissions / sudoers (Verify this account has permissions to run podman or Verify this account is in the sudoers file)

Ensure the user running NodeZero has sudo privileges, then confirm Podman works under sudo:

sudo podman run hello-world

Podman not installed (Verify that podman is installed)

Install a container runtime — see Container Runtime Installation.

Volume-mount path error (The path ... is not shared and is not known to podman)

Run NodeZero from a directory Podman is allowed to mount. See the Podman documentation for more information.

"Permission Denied" on job execution

Users may encounter a "Permission Denied" error when the NodeZero Runner attempts to execute jobs. This is the same underlying problem as the permissions case above — the user lacks access to the container runtime.

Apply the permissions fix for your runtime under Failed to validate your container runtime, then restart the Runner so it picks up the new permissions:

h3 stop-runner
h3 start-runner {runner-name}

CLI, API and Runner issues

This section provides resolutions for frequently reported errors related to the CLI, API authentication, and Runner operations. If you are facing command issues or your Runner is not appearing in the Portal, see below.

CLI & API

Below are common issues related to the command-line interface (CLI) and API authentication.

"h3: Command Not Found" error

When attempting to use h3-cli, the system returns an error stating that the command cannot be found.

Add h3-cli to PATH

The CLI may not be installed correctly, or it might not be included in the system’s PATH variable. To fix this:

export PATH="$H3_CLI_HOME/bin:$PATH"
echo 'export PATH="$H3_CLI_HOME/bin:$PATH"' >> ~/.bashrc

After running these commands, restart your terminal and verify the installation by executing:

h3 --version

Portal issues

This section helps troubleshoot problems related to the NodeZero Portal, including login issues, data clearing steps, and asset group authorization requirements.

Google Chrome cache

Users may experience login or loading issues with the Horizon3.ai Portal due to cached data.

Login or load issues with the Portal

The Portal fails to load correctly or users are unable to log in.

Clear Chrome application data

Follow these steps to clear app data in Chrome:

  1. Open Chrome DevTools (Cmd+Opt+I on Mac / Ctrl+Shift+I on Windows/Linux).
  2. Navigate to the Application tab.
  3. Under Storage, click Clear site data.

NodeZero exiting prematurely

NodeZero can get stopped by Endpoint Detection and Response (EDR) services running on the same host machine. To prevent this from occurring, remove or disable any EDRs on the NodeZero host.