# Troubleshooting

The messages hq prints, what each one means, and the fix.



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

## Signing in [#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 AI Team Cloud Computer 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 … (readable only by you).` | Not an error. The file is `~/.hq/credentials.json`, or `credentials.json` in the folder `HQ_HOME` names when you set it. 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 … (readable only by you).`                                    | Not an error. The file is `~/.hq/credentials.json`, or `credentials.json` in the folder `HQ_HOME` names when you set it. On Linux, install `secret-tool` (libsecret) and sign in again if you prefer the keychain. |

## Teams and access [#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 AI Team Cloud Computers 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 an AI Team Cloud Computer [#connecting-to-an-ai-team-cloud-computer]

| Message                                                                                                                                                                | What to do                                                                                                                                                                                                                                                                       |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hq: waking team "…", this usually takes 15-30 seconds...` (30-45 seconds on Boost Max) or `hq: starting team "…" fresh (about 60 s)...`                               | Progress, not an error. Wait.                                                                                                                                                                                                                                                    |
| `hq: team "…" did not wake within … minutes. Check it in HQ and try again.` (3 minutes, 4 on the sizes from 80 GB)                                                     | Open the team in HQ to see its state, then try again.                                                                                                                                                                                                                            |
| `hq: team "…" has no running Cloud Computer. Open the team in HQ and start a session to start it.`                                                                     | The Cloud Computer is off, not sleeping. `hq up` only wakes a sleeping Cloud Computer; starting a session in HQ starts it.                                                                                                                                                       |
| `hq: the AI Team Cloud Computer is not available right now.`                                                                                                           | Try again in a moment, or open the team in HQ.                                                                                                                                                                                                                                   |
| `hq: the AI Team Cloud Computer went to sleep.`                                                                                                                        | It idled out. Run `hq up <team>` and connect again.                                                                                                                                                                                                                              |
| `hq: team "…" runs an older Cloud Computer image without remote access.`                                                                                               | A team owner (or an organization owner or admin) updates the Cloud Computer: the team's Settings → Update Cloud Computer.                                                                                                                                                        |
| `hq: this AI Team Cloud Computer needs an update before it accepts this connection. An owner or admin can update it in HQ.`                                            | Same fix.                                                                                                                                                                                                                                                                        |
| `hq: team "…" cannot forward ports yet: its AI Team Cloud Computer started before Developer access was turned on. Restart the AI Team Cloud Computer, then try again.` | Developer access was turned on while the Cloud Computer was running. An owner or admin presses **Restart Cloud Computer** in the **Cloud Computer** section of the team's Settings in HQ. Sessions pause and come back where they were. This usually takes about 5 to 6 minutes. |
| `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 AI Team Cloud Computer 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 AI Team Cloud Computer 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 [#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 so you can no longer watch the session (for example, your role on the team no longer lets you view sessions), or the session was closed. `hq` exits.                                                                                        |
| `hq: View only: your role doesn't let you type here.`                          | Your access changed while you were attached, or you are watching. What you type is not sent, and `hq` keeps streaming. The line repeats at most every few seconds while you type. To type again after your access is restored, press `Ctrl-]` and attach again. |
| `hq: the session stopped.`                                                     | The session was stopped in HQ or by a schedule. Start it again in HQ, then attach.                                                                                                                                                                              |
| `hq: the session exited with an error.`                                        | The session's process ended with an error. Open it in HQ to see why.                                                                                                                                                                                            |
| `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 Cloud Computer is starting: `hq` prints progress, and
`hq: Taking longer than usual, still working.` when it takes longer than 30 seconds (45 seconds on Boost Max). 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. In your own session, your role on the team may
not allow typing; an owner or admin can change 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 [#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 [#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 [#commands]

| Message                                         | What to do                                                        |
| ----------------------------------------------- | ----------------------------------------------------------------- |
| `hq: unknown command "…". Run hq --help.`       | Check the spelling against [the reference](/docs/cli/reference/). |
| `hq: missing arguments for "…". Run hq --help.` | The command needs a team, session or port.                        |

## Still stuck? [#still-stuck]

Email [support@aiworkforceone.com](mailto:support@aiworkforceone.com) with the output of
`hq --version` and the exact message. Never include the contents of `~/.hq`.
