Troubleshooting

Two places answer most questions: the console’s Agents page (is the agent connected, does it forward the hostname, does DNS point at the edge?) and the preview’s Requests tab (what did Houseguest™ decide for each request?). Agent problems have their own page: Agent troubleshooting.

Pages viewers see

Page or message	Cause	Fix
No preview is open here	No preview has ever used this hostname	Check the address. Open a preview on it
This preview has ended	The preview’s time ran out or it was ended	Open a new preview, or extend it if it is still open under another name
This preview opens time	The preview is scheduled	Wait, or Open now on the preview
This preview needs an invite	No sign-in for this preview in this browser	See Signed in, but sent back
This invite link no longer works	The invite was used, expired, or the viewer was revoked	Send a new invite
This preview is not available	The workspace is paused	Contact Houseguest
This preview has reached the number of people it can have	The people-per-preview limit	Remove someone, or ask us to raise the limit
The app is not reachable right now	No connected agent forwards this hostname	Check Agents: Agent troubleshooting
Houseguest agent: the app did not answer.	The agent cannot reach or verify the app	Agent troubleshooting
Houseguest agent: this hostname is not shared.	The agent does not allow this name	Agent troubleshooting
Too many codes from this network	More than 10 code requests from one network in an hour	Wait an hour
A browser certificate or connection error	No certificate could be issued for the name	See Certificate errors

No code arrives

1. Check the preview’s Requests → Sign-in. Code sent means Houseguest handed the email over. Not on the list means the address is not covered by the standing-access list, or the person was revoked.
2. Check the spam or quarantine folder. Codes come from Houseguest under your workspace’s sender name.
3. A new code can be sent after 30 seconds, up to 5 an hour per invite or address.
4. Your workspace may have reached its daily email limit: the viewer sees “The code could not be sent. Try again in a minute.” The count resets at 00:00 UTC.
5. If one address never receives mail while others do, it may have bounced once before (for example a mailbox created after the first invite). Contact us with the address.

Signed in, but sent back to the invite page

• The preview’s bare address was opened, not the invite link. An invite preview never opens from its address alone, and the page does not say who is invited. Open the link in the invite email (its Open the preview button, or the address in its first line, which links to the same invite). For a terminal share, houseguest share prints a one-time link for the sharer.
• The app calls a hostname that is not in the preview. Add it on the preview’s Hostnames tab (it must be under the same parent domain).
• The app makes requests without cookies (API calls with a bearer token or credentials: "omit"). They are refused. Use Open without sign-in for harmless paths, or Cookie-less calls from a viewer’s network: see Previews.
• The invite was used in another browser. Send a new invite.
• The viewer was revoked, their list entry removed, or their session length ran out. Re-invite them or add their exact address.
• On a Houseguest address, the app redirects to or links its internal hostname. Share it on its own hostnames instead: see Domains and addresses.
• On a self-hosted edge, the hostnames’ shared parent is a public suffix (such as co.uk), so browsers drop the cookie. Use hostnames under a domain you own.

Certificate errors

The edge issues a certificate for a shared hostname only when:

• on the hosted service, the hostname is under a domain your workspace has verified;
• a connected agent of your workspace forwards it right now;
• its public DNS points at the edge (an A record, or a CNAME to your target).

Check the agent’s page: the hostname should show DNS ok and the agent Connected. Then:

• Use DNS-only records, not a CDN proxy.
• Remove any AAAA record for the name: certificate checks may use IPv6 and fail.
• After fixing DNS, reload the page, or turn the hostname off and on again.

Houseguest addresses use one certificate per workspace, which the edge gets by itself. The first address of a new workspace can take 1 to 2.5 minutes to answer while it is issued; if an address shows a certificate error after that, contact us.

A hostname is not offered in New preview

Cause	Fix
No connected agent forwards it	Check Agents; turn the name on for a wildcard agent
(Hosted) its domain is not verified	Verify it on Domains & addresses, or use Houseguest addresses
Another preview holds it	End or edit that preview. A hostname is in one open or scheduled preview at a time
The hostnames you ticked do not share a parent domain	Use separate previews

Domain verification

Message	Fix
Not verified: no TXT record _houseguest.<domain> with the value houseguest-verify=… yet	Check the record’s name and value at your DNS provider, wait a few minutes, Check now
TXT record found with another value	Replace the value with the one the console shows
another account has verified this domain	Verify a narrower domain you control, or contact us
Not removed: an open preview uses a name under this domain.	End the preview first

Console messages

Message	Cause	Fix
Not allowed: this needs the "<permission>" permission. An admin can grant it.	Your role does not include it here	Ask an admin for a role that does
This form has expired. Reload the page and try again.	The page is from an older session	Reload
Cross-site request refused.	The request did not come from the console’s own page; some privacy extensions strip the Origin header	Use the console’s page; allow the header for the console
Signed out. Sign in again.	The session ended	Sign in
This account is suspended. Contact Houseguest support.	The workspace is paused	Contact us
Too many codes were requested. Try again in an hour.	Console code limit: 5 an hour per address, 20 per network	Wait
Set up a passkey or an authenticator app first	Your workspace requires a second sign-in step	Add one on Sign-in and security
limit reached: …	A workspace limit	See Limits
The hostnames in one preview must share a parent domain, so one sign-in covers them all.	Hostnames under different domains	Separate previews

Command line and browser terminal

Message	Fix
could not reach <host>	Check the address. If your local DNS answers for the name itself, add --edge-ip to houseguest login
<host> answered 404: is a preview open there?	Use the preview’s landing address
Browser shows Open the preview first	Open the invite link in that browser, then the approval address again
the code expired; run login again	Enter the code and approve within 10 minutes
Update houseguest to sign in: …	houseguest before 0.4.0. Run the install command shown to upgrade
Browser shows This code does not match a sign-in waiting here	Check the code in the terminal. It works once, for 10 minutes, in the browser that first entered it
Browser shows Too many codes entered	10 codes that matched nothing in an hour. Wait, then run the command again
not signed in, or the sign-in ended: run houseguest login <host>	The preview ended, or you were revoked. Sign in again if it is still open
That service is not part of this preview.	Check the name:port; ask the sharer to add the service
The service is not reachable right now.	The agent does not report the service, or cannot reach it. Check HG_ALLOW_TCP and the internal address
several sign-ins and none covers <name>: add --via <preview address>	Add --via
The server’s host key has changed.	Confirm the new fingerprint with the server’s owner before trusting it