This page covers common issues encountered when using Commander and how to resolve them. If you continue to experience problems after following these steps, contact Luxor support.
Symptom: Agent shows "Disabled" or disconnected in the Agents table on the Dashboard.
SSH into the agent machine and confirm the agent process is running.
Check if the systemd service (Linux) or Windows Service is active and that the watchdog/restart mechanism is functioning - it should auto-restart the agent if it crashes.
Test outbound connectivity on port 9001 from the agent machine:
Both should report a successful connection. If either fails, outbound TCP on port 9001 is blocked - this is the most common cause of connection failures. Work with your network team to allow traffic to these endpoints. Site firewalls, content filtering policies, and NAT configurations can all block this port.
Check agent logs for connection errors:
Linux: sudo journalctl -u commander-agent -f
Windows: Event Viewer > Windows Logs > Application, filter by source CommanderAgent
If the agent was previously working and has stopped: try reinstalling the agent binary with the same Agent ID and Secret.
If firewall changes were recently made at the site: the agent may need a restart after rules are updated.
If basic network and firewall checks pass and the agent still won't connect, escalate to the Luxor Systems team with the following information: Agent ID, agent machine OS and architecture, network topology details, and agent logs.
Symptom: You need to re-deploy or reconfigure the agent but no longer have the secret key.
You do not need to delete and recreate the agent. Navigate to Settings, click the edit icon on the agent row, enter a new value in the Secret field, and click Update. Then update the agent configuration on your on-site machine with the new secret and restart the agent service. The Agent ID and all configuration (network ranges, site assignment) are preserved.
Symptom: The Agent Version column shows an outdated version despite agents generally auto-updating.
Re-download the agent binary and install it over the existing installation. The new version will replace the old one while preserving your configuration. If the agent download link is only accessible during the initial setup flow, create a temporary agent to get the download, install the binary on your existing agent machine, then delete the temporary agent from Settings.
Symptom: Miners not appearing in the Miners tab after the agent is connected and enabled.
Verify the IP ranges configured in the agent match the actual IP addresses of your miners. Use the tightest possible range matching your DHCP pools.
Confirm the agent machine is on the same LAN or subnet as the miners. For multi-container or multi-VLAN sites, ensure routing exists between the agent and miner subnets.
Wait for a full scan cycle - this can take a few minutes for large IP ranges.
If using multiple network segments, consider deploying multiple agents, each scanning a different IP range.
Symptom: Miners show "Failing" when they are actually operational.
Known causes include miners in a ramp-up phase being reported as Failing until they are fully operational - this has been addressed in recent agent versions. Ensure your agent is running the latest version by checking the Agent Version column in the Agents table.
Symptom: A bulk action fails or partially completes.
Check the action detail page in the Actions Log for per-miner execution logs - this will show which miners succeeded and which failed, along with error details.
If the agent disconnected mid-action, re-execute the action for the remaining miners after confirming the agent is back online.
"Escalate privileges" errors indicate firmware-level permission issues on the miner itself - check the miner's local admin credentials.
Review the Compatibility column in the Bulk Preview before executing to ensure all selected miners support the intended action.
Recommended batch sizes: For large-scale operations, consider using the Batch Size setting in Bulk Preview rather than the default "All at once." Firmware installs and updates are more resource-intensive and benefit from smaller batches (e.g., 50-100 miners per batch with a short delay). Pool changes, power adjustments, and reboots are lighter and can be run in larger batches or all at once.
Symptom: Sitemap page shows empty racks or missing data.
Verify the CSV used for rack/position mapping was uploaded correctly and that the IP or MAC addresses in the CSV match the miners discovered by the agent.
Empty KPI values in the sitemap indicate that the mapped miners are not yet reporting telemetry data - confirm they appear in the Miners tab first.
Check that the correct Site is selected in the Site dropdown at the top of the Sitemap page.
Symptom: A trigger is enabled but has not executed when expected.
Confirm the trigger's Status toggle is set to Enabled.
Review the trigger's conditions - use the Miners table with the same filters to verify that miners currently match the trigger's criteria.
Check the Stop Condition settings. If Max Attempts has been reached within the Attempts Interval, the trigger will not fire again until the interval resets.
Verify the trigger is scoped to the correct Site(s).
Cross-reference the Actions Log to see if the trigger has fired recently - it may have executed but the resulting action failed.
