Common Setup Issues

This section offers solutions to common installation, configuration, and operational issues encountered with NodeZero. Whether you’re dealing with connectivity problems, Docker 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.

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.

Preconfigured OVA: Review the list of required domains for the Preconfigured OVA setup in the OVA setup documentation.
Manual Installation: Review the list of required domains for the Manual Installation setup in the Manual Installation documentation.

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 n0 utility.

Open a terminal and run the n0 command.
Select option 3 to configure a static IP.
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).
Verify the new IP configuration:
```
ip addr show
```
Test connectivity with the new static IP:
```
ping <static-ip>
```
If changes don’t apply immediately, reboot the host:
```
sudo reboot
```
To revert to DHCP, rerun the n0 utility, select option 3, and choose the DHCP toggle.

Docker permission issues

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

"Failed to validate docker" error

Users may encounter the error message 'Failed to validate Docker,' preventing NodeZero from functioning correctly.

Ensure user belongs to Docker group

This error often occurs when the user executing Docker commands does not have the necessary permissions. To resolve this, ensure that the user is part of the docker group by following these steps:

Check your current username:
```
whoami
```
Add yourself to the Docker group:
```
sudo usermod -aG docker $(whoami)
```
Verify that you have been added to the Docker group:
```
groups $(whoami)
```
Either log out and log back in or restart your machine for the changes to take effect.

"Permission Denied" on job execution

Users encounter a "Permission Denied" error when attempting to execute jobs, which prevents the NodeZero Runner from functioning properly.

Grant appropriate Docker permissions

The error is usually caused by insufficient user permissions to access Docker or required files. To resolve:

Add the user to the Docker group:
```
sudo usermod -aG docker $USER
```
Log out and log back in for the changes to take effect.
Run the Runner with appropriate access permissions:
```
sudo h3 runner install --name my-runner
```

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.

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:

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