Agent troubleshooting

Start with the agent’s log on its host:

docker logs --tail 50 houseguest-agent     # or: journalctl -u houseguest-agent -n 50

and the console’s Agents page: is the agent Connected, and does it forward the hostname?

The agent does not connect

Log line	Cause	Fix
not joined yet: set HG_JOIN to a join token from the console (it is used once)	The agent has no key for this edge: a new or deleted volume, or HG_EDGE changed	Create a new join token and set HG_JOIN
join refused (403): join token unknown, used or expired	The token was used, is older than 1 hour, or was mistyped	Create a new join token
join refused (403): limit reached: this account can have N agents; remove one first	Your workspace is at its agent limit. The token is not spent	Remove an unused agent, then start again with the same token within the hour
tunnel down: edge answered 401: Unknown agent.	The agent was removed in the console	Join again with a fresh volume and a new token
tunnel down: edge answered 403: This account is suspended.	The workspace is paused	Contact Houseguest™. Agents reconnect by themselves once it is resumed
tunnel down: edge answered 401: Not authorised.	The host’s clock is more than 2 minutes off, or HG_EDGE names another edge than the one the agent joined	Fix the clock (NTP). Check HG_EDGE
tunnel down: edge answered 426: Upgrade required.	A proxy between the agent and the edge strips the Upgrade header	Allow a direct connection on 443
tunnel down: … x509: …	Something intercepts TLS to the edge, or HG_CA_FILE was set by mistake	Allow a direct connection on 443. For your app’s internal CA, use HG_UPSTREAM_CA_FILE
tunnel down: dial tcp …: i/o timeout or no such host	No outbound 443, or DNS cannot resolve the edge	Open outbound 443. If local DNS answers wrongly for the edge’s name, set HG_EDGE_IP
Connects, then tunnel down about every minute	Two agents share one key (two containers on one volume)	Run one agent per volume
The container exits at start with … is too broad…, … has no address…, HG_ALLOW lists no hostnames or an HG_ALLOW_TCP message	A setting is malformed	Fix it: see Allow-lists
The container exits at start with <host>: address "dns" needs host:port	The agent is older than 0.3.0 and does not know HG_UPSTREAM=dns	Use the console’s image (0.3.0 or later), or give an address instead of dns
… holds no certificates	HG_UPSTREAM_CA_FILE does not contain a PEM certificate	Point it at the CA’s PEM file

The agent retries by itself: after 1 second, doubling up to every 30 seconds.

The agent is connected, but the app does not load

What viewers see	Cause	Fix
The app is not reachable right now (a Houseguest page)	No connected agent of your workspace forwards this hostname	Check Agents: is the agent connected, and is the hostname turned on?
Houseguest agent: the app did not answer. (plain text)	The agent is connected, but could not reach or verify the app. Its log says upstream <host>: <reason>	See below
Houseguest agent: this hostname is not shared.	The edge sent a name the agent does not allow. Its log says refused host "<name>"	See below
Houseguest agent: <host> resolves to … or … does not resolve with this network's DNS … (plain text)	The agent finds addresses with DNS (dns) and the answer was not an internal address. Its log has the same text after upstream <host>:	See below

upstream <host>: … in the agent’s log:

• x509: certificate signed by unknown authority: the app uses an internal CA. Give the agent the CA: Apps with an internal CA.
• x509: certificate is valid for …, not <host>: the internal address serves a certificate for other names. Point the agent at the reverse proxy that serves this hostname.
• connection refused or a timeout: wrong internal address, or the container cannot reach it. Check the address; try --network host.
• The app speaks plain HTTP: the agent always uses TLS. Put a TLS reverse proxy in front of the app.

upstream <host>: <host> resolves to … in the agent’s log (with HG_UPSTREAM=dns):

Message	Cause	Fix
resolves to the Houseguest edge (<ip>), so the request would loop back to it	The agent’s DNS has no internal record for the name, so it got the public one, which points at Houseguest	Add the internal record, or give the name an address: <host>=10.0.0.5:443 in HG_ALLOW
resolves to a public address (<ip>)	No internal record, or the container asks a public resolver	Add the record, or an address; set --dns to your internal resolver. For a public app, HG_ALLOW_PUBLIC_DNS=1
resolves to a loopback address / a link-local address	The record points at 127.x or 169.254.x	Fix the record, or write the address in HG_ALLOW
does not resolve with this network's DNS (no such host)	No record for the name	Add the record, or an address
(the DNS server failed to answer) / (… did not answer in time)	The resolver failed	Fix the resolver, or point the container at another with --dns

A fixed record takes effect within 5 seconds.

refused host "<name>" in the agent’s log:

• The name is two labels under a wildcard (a.b.example.com under *.example.com). Add an exact entry.
• The agent runs with HG_REMOTE_HOSTS=off, so it ignores names turned on in the console. Add an exact entry, or remove the setting. (The console still lists such names as on.)
• HG_ALLOW changed on the host. Turn the name off and on again in the console, or restart the agent.

The console shows the agent as offline

Agents shows how long an agent has been offline and how many open previews use it. Common causes: the host restarted without Docker starting the container (check --restart unless-stopped), the host lost its network, or the container was stopped. Start it again with the same volume; it reconnects as the same agent.

Still stuck

Collect the last 50 lines of the agent’s log, the agent’s name and the time it happened, and contact us. Never send the join token.