Symptom on the left, what to check on the right. Everything here is a real failure mode
with a real cause; where the cause is a design decision rather than a fault, the row says
so.
/var/log/wheelhouse-install.log. The installer names it in its own error, and the failure screen offers to show it.
The installer never appeared, just a login prompt
You are on a serial console, or the machine booted an installed system rather than the medium. The banner on a serial console says to run sudo wheelhouse-install; on an installed system that command refuses and says so.
A seeded install did nothing
/var/log/wheelhouse-install.log, lines prefixed autoinstall:. Run sudo VERBOSE=1 wheelhouse-autoinstall to see which seed it would pick.
A seeded install ran once and then stopped trying
By design. An unattended install runs at most once per boot — /run/wheelhouse-autoinstall.attempted.
The seed was ignored on a machine that already has a system
By design. Set overwrite: true in the seed, or remove the medium.
DISK=auto refused
There is no disk that is not the boot medium, or there is more than one. Name one.
A seed URL was refused
Plain http:// or ftp://. Serve it over HTTPS, or boot with wheelhouse.insecure=1 if you trust that network.
No Web UI: line on the banner
The machine has no address yet. ip -4 addr from the console.
The banner says the agent is not active
journalctl -u wheelhouse-agent.
The installer warned about no IPv6 firewall
The image has no firewall ipv6 node, so only the IPv4 ruleset was written. Write the v6 filter before you turn IPv6 on.
The appliance is 8443; the developer install is 8090.
The browser cannot reach 8443
The firewall, the wrong interface, or a stopped agent. From the console: curl -k https://127.0.0.1:8443/health.
A box with a WAN and no LAN cannot be reached at all
The default-deny filter admits nothing from the WAN. That is the design. Reinstall with a MGMT_SOURCE, or add a rule from the console.
The browser warns about the certificate
--tls-self-signed is self-signed by definition. Add a security exception for this host, or install a real certificate. Do not import it into a root store — it is a leaf certificate for one host.
The UI is blank
The agent was started without --ui-dir, or the assets are missing. After an agent upgrade, hard-reload once: index.html carries no cache policy yet, so a stale copy can ask for an asset hash that no longer exists.
The agent cannot reach the router. Check --api-url and the API key: sudo cat /config/wheelhouse/api-key, and show configuration commands \| match 'service https'.
502 … answered HTTP 404 … (is service https api rest configured?)
The router's REST endpoints are off. With only a key configured, its API answers 404 to everything. set service https api rest.
is mode 644; it must not be readable by group or other
chmod 600 that file. The agent refuses to read a loose secret.
The agent will not start: another agent is running against this data dir
A stray process holds the data directory. systemctl stop wheelhouse-agent, check for a second one, start again.
The agent will not start: the state file is newer than this agent
You downgraded. Reinstall the newer agent; opening it would silently drop fields it does not understand.
A commit was refused
The message is the router's own words. A rejected command arrives as HTTP 200 with an error field, which is why it surfaces as a 502 rather than a false success.
The router rebooted after a commit
A commit-confirm window expired unconfirmed. That is the feature working — the reboot is how the rollback is implemented.
A rollback answers 502
The archive file for that revision is missing. ls /config/archive.
The 1:1 NAT editor is disabled
By design, and the page says why: committing nat static through this build's HTTP API stops the API process. Make those rules from the command line; the table still reads them.
Packet capture answers 501
Not implemented. The response carries the monitor traffic command to run by hand.