Troubleshooting
Find the layer that fails before you retry, switch accounts, or change session data.
Checked against the source on 5 October 2026
On this page
A task will not start
- Open Settings → Agents.
- Make sure that the agent of the session is signed in. Codex needs a ChatGPT sign-in, and Claude needs a Claude sign-in.
- Look at the usage limits of the active account on the same page.
- In the session, look for an approval request that waits for your answer.
- Look at the queue of the session. A held entry shows why the desktop holds it. Each entry has the actions Send now, Edit, and Delete.
- Read the error on the screen before you send the instruction again.
A message in the queue is safe on the desktop. A message in the timeline got to the agent, so examine that run. If the message is not in the queue or in the timeline after a reconnect, keep the error text for your report.
| Symptom | Cause and action |
|---|---|
| Claude: a message sent during a run shows “Sends after the current step”. | Claude reads the message after its current step, between two tool rounds. To send it immediately, use Stop and send now on the message. |
| A message returned to the queue with “The active run stopped before this message reached the agent.” | The run ended before the agent got the message. Examine the message. Then send it again. |
| Claude: the run fails at once with “does not support Auto mode”. | The access level Auto mode needs a model that supports it. Select a different model or a different access level. |
| Claude: the error says “The Claude runtime is not packaged”. | The desktop did not find the Claude runtime in its resources. A Codex session still runs. |
| Claude: a switch of the account did not change the running run. | A run keeps the account that was active at its start. The switch applies to the next run. |
| Codex: the limit meters show the old profile after a switch. | The desktop keeps one Codex limit reading for 60 seconds, and a switch does not clear it. Read the meters again after 60 seconds. |
The phone cannot reach the workspace
| Check | Action |
|---|---|
| Account | Sign in to both apps with the same HB Code account. A shared Chat |
| Region | Select the same server region on both devices. A change of the region signs out the old session. |
| Remote access | On the desktop, open Settings → Connections. Set Allow Remote Access to on. |
| Computer state | Make sure that the computer is awake and that the desktop app is open. A laptop that sleeps loses its relay connection. The server then shows the desktop as reconnecting for 90 seconds and after that as offline. |
| Network and readiness | Read the connection banner on the phone. Use its reconnect action. |
A bundled tool is not available
| Tool | Check |
|---|---|
| Browser control | Make sure that the Browser Bridge extension is installed and on in Chrome 120 or later. Make sure that Enable Browser Bridge is on under Settings → Connections. Make sure that HBCODE_ |
| Speech and video | Make sure that Settings → API Keys has a Gemini API key. Without a key, the two tools are not in the tool list. After you save a key, the rule is different for each agent. A Codex thread keeps the tool list that it started with, so start a new Codex session. A Claude run gets the current list, so send the next message. |
| Push alerts from the agent | Make sure that Desktop and phone notifications is on under Settings → General. Make sure that the phone allows alerts. Make sure that the desktop shows its relay connection as online. The alert tool is in the tool list only while notifications are on. After a change, the rule for each agent is the same as for speech and video. |
| HTML documents | The link in the chat opens the preview. If a document is missing, its file on the desktop is gone, or the desktop is offline for the phone. |
| Tool calls in a Claude session wait | Claude asks before a bundled tool call as the access level says. Answer the approval card. Session lookup and session messages run without a card. Codex runs bundled tools and asks no question. |
A message from another session waits
An agent sends a message to another session with the tool send_session_message. The message goes into the outbox of the recipient. A recipient that runs gets it in its running turn, and a recipient that does not run starts a turn for it. The desktop holds the message for you in the three cases of the table. It checks the rules again just before delivery, because the recipient’s settings can change while the message waits.
| Text on the held entry or in the tool result | Cause and action |
|---|---|
| This session has more access than the session that sent the message. | The access level of the recipient is above the level of the sender. The order is read-only, full-auto, full-access, unrestricted. To approve the message, use Send now. Or decrease the access level of the recipient. |
| The running turn’s access could not be confirmed. | The recipient runs a turn, and the desktop cannot read the access of that turn. To approve the message, use Send now. |
| The session could not be read. | The desktop could not read the recipient session when it checked the message. To approve the message, use Send now. |
Send now approves a held message. The turn then runs with the access level that the recipient has at that moment. A reply comes later as a new message in the queue of the sender. The sending agent does not wait for it.
History is loading or a source is missing
A live connection and a history read are separate steps, so a connected banner with an empty timeline points at the read. Use Retry loading in the timeline. This applies to both agents: Codex history comes from the app-server, and Claude history comes from the agent host.
The next two cases are Codex only. When an attached external Codex session reports a missing source, Choose source file lets you select the intended file yourself. HB Code does not swap in a similar file from another profile. An attached Zstandard-compressed rollout loads read-only: history shows, and sends are blocked until you decompress it and attach the JSONL. When you repair a link, keep the original file. Make sure that the selected source is the correct file.
Write a report someone can reproduce
App and version:
Desktop OS / iOS or Android version:
Selected server region:
Steps to reproduce:
Expected behavior:
Actual behavior and visible error:
Approximate time:
Did the same action work on desktop?
Relevant screenshot or bounded log excerpt: