Troubleshooting

Every hq message starts with hq:, and … below stands for a team, session or organization name.

Signing in

Message	What to do
hq: you are not logged in on this computer. Run hq login.	This computer has no stored login, or you ran hq logout. Run hq login.
hq: your HQ login on this computer expired or was revoked. Run hq login.	HQ no longer accepts this computer. Run hq login.
hq: your HQ login on this computer needs renewing. Run hq login.	Run hq login.
hq: this connection was refused. Your login may have expired: run hq login.	Same fix: run hq login.
hq: the team machine refused this computer's key. Run hq login again.	Run hq login.
hq: the login was denied in the browser.	Someone chose Deny on the approval page. Run hq login again.
hq: this login code expired. Run hq login again.	The 10 minutes ran out. Start over.
hq: "…" must use https:// (only localhost may use http).	Give --host or HQ_HOST an https:// address.
hq: "…" is not an HQ address like https://hq.aiworkforceone.com	Check the address: scheme, host and optional port, nothing else.
hq: the system keychain is not answering (no Secret Service running), so your login is stored in ~/.hq/credentials.json (readable only by you).	Not an error. Start your desktop keyring and sign in again if you prefer the keychain.
hq: no system keychain tool found, so your login is stored in ~/.hq/credentials.json (readable only by you).	Not an error. On Linux, install secret-tool (libsecret) and sign in again if you prefer the keychain.

Teams and access

Message	What to do
hq: no team "…" on this login. Run hq status to see your teams.	Use the hq-… name or the exact team name from hq status. A team you were just added to shows up after you run it.
hq: "…" matches more than one team. Use the hq-… name from hq status.	Two teams share the name; the hq-… name is unique.
hq: team "…" was not found. Run hq status to refresh your teams.	The team was removed or renamed. Run hq status to see your teams.
hq: you do not have remote access to team "…".	You need editor or owner access for forwarding (viewer is enough to attach). Ask an owner.
hq: remote access to this team is not allowed for you right now.	Same cause, reported at connection time.
hq: remote access is not available for … yet.	Developer access is off for that organization. An owner turns it on in HQ, under Settings, Security, Developer access.
hq: remote access is not available on this HQ.	This HQ address does not offer remote access. Check the address.
hq: connections to team machines are not switched on for this HQ yet. Ask an owner or admin.	Remote connections are off on this HQ. Ask an owner or admin.

Connecting to a team machine

Message	What to do
hq: waking team "…" (about 15 s)... or hq: starting team "…" fresh (about 60 s)...	Progress, not an error. Wait.
hq: team "…" did not wake within 3 minutes. Check it in HQ and try again.	Open the team in HQ to see its state, then try again.
hq: team "…" has no running machine. Open the team in HQ and start a session to start it.	The machine is off, not sleeping. hq up only wakes a sleeping machine; starting a session in HQ starts it.
hq: the team machine is not available right now.	Try again in a moment, or open the team in HQ.
hq: the team machine went to sleep.	It idled out. Run hq up <team> and connect again.
hq: team "…" runs an older machine image without remote access.	An owner or admin updates the machine: the team's Settings → Update machine.
hq: this team machine needs an update before it accepts this connection. An owner or admin can update it in HQ.	Same fix.
hq: team "…" must restart its machine before remote access works (…)	Developer access was turned on while the machine was running. An owner or admin presses Restart machine in the Machine section of the team's Settings in HQ. Sessions pause for about two minutes and come back where they were.
hq: too many connection attempts right now. Wait a minute and try again.	Wait a minute.
hq: too many open connections to team "…". Close one and try again.	Close an editor window or terminal you no longer need.
hq: HQ is restarting. Try again in a moment.	HQ is deploying. Try again in a few seconds.
hq: the team machine did not answer in time. Try again in a moment.	Try again; if it repeats, check the team in HQ.
hq: your access to this team ended (revoked, expired, or remote access was turned off).	Your access changed while you were connected. Run hq status to see what you can reach now.
hq: this connection was closed from HQ.	Someone closed it in HQ. Connect again if you still need it.
hq: connections end after 12 hours. Connect again to continue.	Reconnect.
hq: the team machine could not be reached (HTTP …). or hq: the connection closed (…).	Try again. If it repeats, send the message to support.

A reconnect did not wake the team. When hq reaches a sleeping team for what looks like a background reconnect, HQ does not wake it, and hq says to run hq up. Run hq up <team> or open the team in HQ, then reconnect.

Attach

Message	What to do
hq: no session "…" you can open. Sessions are listed in HQ on the team page.	Check the name or id on the team page in HQ. You need viewer access or more on that team.
hq: "…" matches … sessions. Use more of the id:	hq lists the matches with the first 8 characters of each id. Attach with one of them.
hq: could not reach HQ.	Check your network, then attach again.
hq: could not reach HQ (…).	The same, with the network error. Check your network and try again.
hq: connection lost, reconnecting...	Progress: hq retries on its own, up to 8 times in a row.
hq: the connection to HQ was lost.	The retries ran out. Check your network and attach again.
hq: your access to this session ended.	Your access changed, or the session was closed.
hq: you can watch this session but not type in it.	Your access changed while you were attached. You keep watching.
hq: local echo is not available on this HQ yet.	Your organization or this HQ does not allow local echo. hq attaches without it.
hq: --local-echo takes auto, always or off.	Use one of those three values.

Nothing happens after attaching. A sleeping machine is starting: hq prints progress, and hq: Still on it... when it takes longer than 20 seconds. If you see Press any key to continue., press a key to wake it.

You cannot type. You are watching someone else's session: the first line said view only. Only the person who started a session types in it.

Ctrl-] does not detach. On keyboards where ] needs another modifier, try Ctrl-5, which sends the same key code in most terminals.

Port forwarding

Message	What to do
hq: the team port must be a number from 1024 to 65535.	Forward the port your server listens on, in that range.
hq: --local must be a port number.	Give --local a number.
hq: no team lets you forward ports. Run hq status to see your teams.	Forwarding needs editor or owner access and remote access on.
hq: more than one team can forward ports. Name one with --team <hq-name>.	Add --team hq-….
listen EADDRINUSE: address already in use 127.0.0.1:…	Something on this computer already uses that port. Pick another with --local <port>.
hq: the forward ended (…).	HQ stopped answering the forward's heartbeat. Start it again.
hq: stream failed (…)	One connection through the forward failed; the forward keeps running. Retry the request.

Signing out

Message	What to do
hq: could not reach HQ to revoke this device (…). Signed out locally.	The login is gone from this computer, but HQ may still list it. Remove it in HQ, under Account, Devices.
hq: HQ did not confirm that this computer’s access ended. Remove it in HQ, under Account, Devices.	Do that in HQ.

Commands

Message	What to do
hq: unknown command "…". Run hq --help.	Check the spelling against the reference.
hq: missing arguments for "…". Run hq --help.	The command needs a team, session or port.

Still stuck?

Email support@aiworkforceone.com with the output of hq --version and the exact message. Never include the contents of ~/.hq.