Troubleshooting

Problem: A reply fails, and Desktop shows a red card in the chat. The iOS app shows the same card. Your message stays in the chat.

Fix: Click the button on the card. A key or sign-in button opens the AI Providers dialog for the provider that failed. When you save the key or sign in, the card shows Connection updated. Your message is saved. Then click Retry message to send the same message again.

Click Show details on the card to read the provider's own message.

If the failed reply ran tools, the card shows Some actions may already have completed. Check the chat, then send a new message. Desktop does not send the message again. A second run can do the same work two times. Look at the chat to see what the agent did. Then type a new message.

If the card shows The message was not sent again. Try again., the retry did not reach the HQ. Make sure that the HQ is on, then click the button again.

In the iOS app, the card shows the same messages. Its repair button opens AI Providers. Tap Retry message after the repair. Refer to When a reply fails.

If you run the HQ without Desktop, add the key with the credentials API of the HQ. A provider environment variable, for example ANTHROPIC_API_KEY, works for chat turns only. Refer to AI Providers.

Problem: Desktop shows This reply failed. No error details are available.

Meaning: The reply failed, but its saved history has no error details. Any partial output stays visible.

Next step: Review any completed work in the chat before you choose what to send next.

Problem: A WebSocket connection to ws://localhost:<port>/ws/chat fails with a refused connection.

Cause: The HQ is off, or the port is not the channel port of the HQ. An HQ that Desktop starts uses a free port. A standalone HQ uses port 9200.

Fix: Make sure that the HQ is on. In Desktop, open Settings → General and look at the HQ section. For an HQ that Desktop starts, read channelPort in ~/.dashsquad/<hq id>/ports.json. If you run the HQ without Desktop, look for this line in the HQ output:

HQ channel server listening on port 9200

Problem: A WebSocket connection on localhost closes immediately with code 4001.

Cause: The HQ did not accept the chat token.

Fix: Send the chat token in the Authorization header as Bearer <chat-token>. A browser cannot set this header, so a browser client sends the token in the token query parameter. The management token does not work on /ws/chat. Refer to the HQ chat WebSocket API.

Problem: The chat returns an error frame with this message:

Agent 'myagent' not found

Cause: The message names a squad member that does not exist on this HQ.

Fix: In Desktop, open the Squad page (Manage next to Agents in the sidebar) and make sure that the name agrees with a squad member. You can also call GET /agents on the Management API.

Problem: Desktop shows Your sign-in changed. Try again to continue with your account.

Cause: The active account or sign-in session changed before setup finished.

Fix: Sign in again with the account that you want to use. Then retry setup.

Problem: After the update to Desktop 0.23.4, your iPhone, iPad or browser cannot reach the HQ. These messages can show:

Cause: After the Desktop 0.23.4 update, some Macs give the HQ a new key for phones and browsers. This occurs one time. After that, the HQ does not accept the old key.

Fix:

• iPhone or iPad: Go to Settings and tap Disconnect & Forget, then confirm. Sign in again and tap the same HQ in the list.
• Browser: The web app shows the HQ list. Select the HQ again.

Disconnect & Forget removes the offline cache, drafts and attachments of that HQ from the device. Copy the drafts that you want to keep before you start. Your conversations stay on the HQ, and they load again after you connect.

In Desktop, click Close to remove the message. It does not show again.

Problem: Desktop shows Your HQ did not start and a line that starts with Reason:. This screen can show in the setup wizard or when Desktop starts. If the setup wizard shows We could not register your HQ, see Remote access.

Fix: Find the reason in this table:

Wait for an HQ to stop before you retry. If cleanup fails, stop that HQ process before you retry. Do not delete hq.lock or hq-lock.guard.db to force a start.

Keep the HQ folder on a local disk. Do not share one folder between computers. Stop an older HQ version before you start a new version on the same folder.

The move error gives one of these reasons:

• ~/.dash and ~/.dashsquad are on different disks: Desktop moves the folders. It does not copy them. Put the two folders on the same disk.
• dashsquad has no permission to change a folder (<path>): Give your user account permission to change that folder.
• the disk is full: Make free space on the disk.
• A different reason is the error text from the system.

For more about the move, refer to Session issues.

For a different reason, click Show the log. Finder shows hq.log in ~/.dashsquad/<hq id>/logs/. Desktop writes its own log to ~/.dashsquad/desktop/mc.log. Your agents, keys and conversations stay on the computer. To close Desktop, click Quit.

Desktop can refuse to start the saved HQ when a different dashsquad account owns it.

After setup, Desktop checks the owner of the HQ when it starts and after each sign-in, also a sign-in in Settings → General. If a different account owns the HQ, Desktop does not show the agents and chats of that HQ. It opens the setup wizard at the HQ step. The screen shows We could not register your HQ and The HQ on this Mac belongs to a different dashsquad account. Set up a new HQ for your account. dashsquad restarts to do this. The other HQ stays on this Mac.

Click Set up a new HQ. Desktop restarts and creates an HQ folder for your account. The other HQ stays on this Mac. Its data and credentials stay separate.

Problem: When Desktop starts, it shows Saved HQ is not reachable.

Cause: Desktop uses an HQ on a different computer, and that HQ does not answer.

Fix: Do one of these:

• Make sure that the remote HQ is on. Then click Retry.
• Click Edit HQ connection to connect to a different HQ or to change the connection details.
• Click Use this computer to start the HQ on this Mac.

Problem: Desktop shows Your agents did not load. on the Agents page or on the chat home screen. The sidebar shows Agents did not load.

Cause: Desktop could not get the agent list from the HQ. For example, the HQ is busy or does not answer yet. Your agents are not lost. The Agents page shows the reason from the HQ below the message.

Fix: Wait a moment, then click Try again. If the message continues, click Restart HQ in Settings → General.

If Desktop already showed your agents, it keeps the old list. The Agents page and the sidebar then show The agent list did not update. It can be out of date. Click Try again to load the list again.

Problem: A change returns HTTP 409 with the code conversation_busy, or the chat returns an error frame with the same code. The error can include an activeTurnId.

Cause: Another turn is active in the conversation.

Fix:

1. Get GET /mobile/v1/conversations/:id again and read its activeTurnId.
2. Replay the events after the last sequence that you applied.
3. To stop the active turn, send cancel with that turn ID. Or let the turn complete.
4. Wait for a terminal frame and for a summary with no active turn.
5. Try the change or the new turn again.

Do not send the prompt again with a new turn ID. That can do the model work two times.

If the message contains the previous turn is still settling, the HQ waits for the previous provider run to stop. This can continue after a cancel, also when the summary shows no active turn. Wait a short time, then try again.

Problem: The next durable WebSocket frame has a higher seq than you expect. Or the socket closed while a turn was active.

Fix: Keep the highest seq that you applied. Then do these steps:

1. Open a new socket, send hello, and wait for hello_ack.
2. Send subscribe_conversation with sinceSeq set to your last seq.
3. Apply the replayed frames in sequence order, lowest first.
4. After conversation_subscribed, the live frames of the active turn continue on this socket.

To read the gap without a socket, request GET /mobile/v1/agents/:agentId/conversations/:conversationId/events?sinceSeq=<last-seq>. Do not send the original message again with a new turn ID.

Problem: PATCH or DELETE returns HTTP 409 with the code revision_conflict.

Cause: Another client changed the conversation first.

Fix: Replace your cached summary with the summary in details.current. Apply your title or metadata change to that summary again. Then send the request again with its revision in a quoted If-Match header. Do not send a delete again automatically. First show or examine the newer state.

Problem: A management request returns HTTP 401. Or a direct chat closes with WebSocket code 4001. Or a chat through the relay closes with code 4401.

Fix: Send the phone's Mobile bearer token in the Authorization header on /mobile/v1 and on /ws/chat. Do not put it in the URL. The relay also needs the x-dash-relay-credential header. That credential does not replace the Mobile bearer token. If someone revoked one of the two credentials, pair the phone again.

Problem: HTTP returns 429, an error has the code rate_limited, or a relayed WebSocket closes with code 4429.

Fix: Stop the fast loop of retries and reconnects. Obey the HTTP Retry-After header, then connect one time. If you get no delay, use exponential backoff with jitter. Reset the backoff after a stable connection. Keep your last applied sequence, so that the next connection replays the gap. Do not send the prompts again.

Problem: The relay returns HTTP 502, or the chat reports gateway_offline. The phone can reach dashsquad but not the paired HQ.

Fix: Turn on the HQ computer and make sure that the HQ is on. The HQ then connects to the relay again. While the HQ is offline, show the cached history as read-only. Do not queue changes, deletes or prompts as if the HQ accepted them. When the HQ is back, get the summaries again and replay from the last sequence.

You do not have to pair again after a usual offline period. Pair again only if someone revoked the device credential.

Cause: The saved HQ is offline.

Fix: Make sure that the HQ is on and that the computer has a network connection. While the HQ is offline, you can read the synced conversations from the cache. You cannot create, send, rename or delete until the HQ connects again.

Problem: The iOS app shows Message saved for recovery, and you cannot type in that chat.

Fix:

1. In Agents, open Needs Recovery.
2. Copy the full message text.
3. Look at or share the attachments that you need.
4. Discard the recovery item. The chat stays read-only until you do this.

If the app cannot read the saved attachment data, you can still copy the text. If a newer draft exists, the app keeps it separate from the saved message.

Cause: Another paired client has the active turn in this conversation.

Fix: Wait for the turn to stop, watch the shared stream in Desktop, or stop the turn. You cannot send a second turn, rename or delete until the active turn stops.

Cause: Another client changed the conversation first. Desktop then loads the current version.

Fix: Look at the current title and state, then do the rename or delete again.

Problem: The app tells you to update dashsquad on the HQ. Each app shows its own message:

Cause: The HQ is older than the dashsquad apps. An older HQ does not send contractVersion in GET /mobile/v1/health, or it sends chat data that the app cannot read.

Fix: Update dashsquad on the HQ computer. Then pair the device again or open the conversation again. If Desktop runs the HQ for you, update Desktop on the HQ computer. Then restart the HQ: click the dashsquad icon in the menu bar, click Quit dashsquad… and click Quit and stop HQ. Then open Desktop again.

Problem: Desktop shows one of these messages in a conversation:

The error stays on the conversation that has the problem. Other conversations continue to operate.

Fix:

1. If Desktop cannot reconnect, make sure that the HQ is on. Then select another conversation and select this one again.
2. If the authorization failed, open Settings → General and click Change HQ. Connect the HQ again with its current tokens. Desktop then opens the conversation again.

Problem: Desktop shows a message that starts with Update dashsquad:.

Cause: When Desktop connected, it could not read an answer from the HQ. The versions of Desktop and the HQ do not agree.

Fix: Update Desktop and the HQ to the same dashsquad version. Do not clear your history. Your conversations stay on the HQ.

Cause: A response failed, or you stopped a response. This pauses the queued Follow Ups.

Fix: If a response failed, read the error and correct the cause. Then click Resume Follow Ups. Before you resume, you can edit or remove the queued items. You can also edit your draft while the queue is paused.

Cause: The response stopped before your Steer got to a safe point. The conversation marks it Not delivered.

The Steer does not run later. If you still need the guidance, send it again as a new message or as a Follow Up.

Cause: Another device edited, removed or started the item.

Fix: Refresh the queue before you edit again. dashsquad keeps the rejected draft text and images, so you can compare them with the current state. Do not send a replacement again and again while a command is pending.

Cause: Send routes your message automatically while a response is active. This is correct behavior.

Fix: Open the chooser yourself:

To see the chooser every time, open Settings → Chat in Desktop. Under While a response is running, select Always ask. This setting applies to all chat apps on the HQ.

The chooser shows only while a response is active. If the chooser still does not open, update the HQ and connect again.

Cause: Automatic routing asks you when it is not sure. These are the usual causes:

• The HQ has no OpenRouter key. Automatic routing needs one. Add it in Settings → AI Providers.
• You selected Always ask in Settings → Chat → While a response is running.
• The message can be a Steer or a Follow Up, and dashsquad cannot decide.
• The routing check took more than 1.5 seconds. dashsquad then asks you.

You cannot cancel a Steer after the agent gets it. Next time, open the chooser before you send, and select Follow Up. Refer to the chooser entry above for the shortcut on each app.

To stop automatic routing, select Always ask in Settings → Chat → While a response is running.

The HQ keeps the Follow Ups that it accepted. Connect again and let the app examine the shared queue before you send another copy. Pending commands keep their original request IDs. On iOS, if you must recover a message manually, use Needs Recovery.

Problem: You added or changed a key in Settings → AI Providers, but the agent still gets an authentication error.

Fix: A new key starts to work on the agent's next message. Send another message. If the error continues, make sure that the key is valid at the provider. Also make sure that you added the key for the provider of the agent's model.

The HQ keeps provider keys encrypted in credentials.enc in its HQ folder. The decryption key is in secret.key in the same folder. For an HQ that Desktop starts, the folder is ~/.dashsquad/<hq id>/. For a standalone HQ, the folder is ~/.dash/gateway/.

Fix: When you copy the HQ folder to another computer, copy the two files together. The HQ cannot decrypt credentials.enc without its secret.key. If you lost secret.key, delete credentials.enc. Then add your keys again in Settings → AI Providers.

Problem: The HQ list in the iOS app shows this message:

Couldn't reach your dashsquad account service. Check your connection and try again.

Cause: The app could not load your HQs. This message does not mean that your account has no HQs.

Fix: Make sure that the phone has a network connection, then tap Retry.

Problem: When you select an HQ, iOS app 0.7.0 or later shows an alert with one of these titles, and Try Again:

For Couldn't connect, the message tells you the cause:

Problem: The HQ list in the iOS app or the web app shows this message:

No HQs linked to your account yet. Open Desktop → Settings → Devices → Remote access to enroll this machine.

Fix:

1. On the computer with your HQ, open Desktop.
2. Open Settings → General.
3. In the Account card, click Sign in. Use the same dashsquad account as in the app.
4. In the HQ card, click Set up remote access. If the card shows Set up my HQ, click it.
5. In the app, tap Refresh.

When the list has HQs, pull down on the list to refresh it.

Problem: When you select an HQ, the iOS app or the web app shows one of these messages:

This HQ needs to be re-enrolled from Desktop before app access works.
This HQ needs to be re-enrolled from Desktop before web access works.

Cause: The relay does not have the chat token for this HQ yet. An HQ that you set up with an older version of Desktop can have this problem.

Fix: Open Desktop on the computer with this HQ. Desktop updates the HQ automatically when it starts: it sends the chat token again. Then select the HQ again in the app.

Problem: The Pair Device section in Settings → Devices shows this message:

Set up remote access in Settings > General.

Cause: Phones reach the HQ through the relay only. The HQ must have remote access first. You do not type an address. Desktop gives the HQ its address.

Fix:

1. Open Settings → General.
2. If the Account card shows Not signed in, click Sign in.
3. In the HQ card, click Set up remote access. If the card shows Set up my HQ, click it.
4. On an iPhone or iPad, sign in to the dashsquad app with the same account. Then choose this HQ. You do not scan a QR code.
5. On Android, click Show QR code in the Pair Device section. Then scan the new QR code.

Problem: Pair Device shows Switch to the local HQ before pairing a device while Desktop uses an HQ on another computer.

Fix:

1. Open Settings → General.
2. In the HQ section, click Use this computer.
3. Wait until the HQ status shows This computer.
4. Open Settings → Devices again to get a new pairing code.

Desktop makes pairing codes only for the local HQ.

Problem: Remote access in Settings → Devices shows this message:

Set up remote access in Settings > General.

Cause: The HQ on this Mac does not have remote access. This can occur if you set up Desktop with an older version, before the setup wizard set up remote access.

Fix:

1. Open Settings → General.
2. If the Account card shows Not signed in, click Sign in.
3. In the HQ card, click Set up remote access. If the card shows Set up my HQ, click it.

Problem: Remote access in Settings → Devices shows this message:

Your phones stay paired. Sign in to change remote access.

Cause: The HQ has remote access, but Desktop is not signed in to your dashsquad account. After an update from an older Desktop that used browser sign-in, you must sign in again one time.

Fix:

1. Open Settings → General. The Account card is on this page.
2. In the Account card, click Sign in.
3. Sign in with your email address, with Google or with Apple.

Your paired phones continue to operate while Desktop has no sign-in. You do not have to choose an organization. Desktop does this for you. If your account has no organization, Desktop makes one with the name "My squad".

Problem: You click Sign in in Settings → General → Account. Desktop shows Sign-in did not finish and a message. Some messages also show on the email, code or password screen.

Fix: Find the message in this table. Then click Try again.

If the problem continues, write to support@dashsquad.ai.

Problem: The setup wizard shows We could not register your HQ and a line that starts with Reason:. Or the HQ card in Settings → General shows an error after you click Set up remote access.

Fix: Find the reason in this table:

If this HQ is the last HQ on your account and the account has no trusted phone, Reset this HQ? shows a message first. The message is Add your phone first, or you will need support to add an HQ again. Remove from account shows the same message.

To add your phone first, click Cancel. Go to Settings → Devices and click Add your phone. If Desktop then shows Adding a first phone is off for now, for a security fix. Your HQ is not affected. It comes back in a dashsquad update., you cannot add a phone yet. To reset the HQ now, click Reset HQ in Reset this HQ?.

When you reset the HQ, Desktop first removes the old HQ from your account. Then Desktop stops the HQ, makes a new HQ folder and starts the setup wizard again. Your agents and conversations stay in the old HQ folder.

If the reset fails, Desktop shows one of these messages:

You do not type an address for the HQ. Desktop gives the HQ its address. The HQ gets the computer name of your Mac. You can change the name in the HQ card.

Problem: Setup shows Add your phone on one of your other HQs first.

Cause: Your account already has an HQ, but no trusted iPhone. A new HQ needs approval from a trusted phone.

Fix:

1. On a Mac that runs one of your other HQs, open dashsquad. Go to Settings → Devices and click Add your phone. The Mac shows a QR code.
2. On your iPhone, open dashsquad and sign in with the same account. Tap Add this Mac, then scan the QR code.
3. The Mac asks if your phone can manage this account. Check that the last 8 characters of the key on the Mac are the same as on your phone. Then click Allow. If they are not the same, click Don't allow.
4. On the new Mac, click Try again. Then approve the new HQ on the phone in Settings → Approve a device.

The QR code works for 5 minutes. If it expires, click Show a new code.

Problem: Your phone could reach your agents through the relay. Then it could not connect. This usually occurs after the computer was asleep or off for a long time.

Fix: Usually you do not have to do anything. The HQ renews its relay connection automatically and connects again, also after a long offline period. Give it some time after the computer starts.

You do not have to set up the HQ again or pair your phone again. If the connection does not come back after some minutes, do these checks:

1. Make sure that the computer is online and the HQ is on.
2. Open Settings → Devices → Remote access.
3. Make sure that it shows HQ ready: and the name of your HQ.

Problem: A phone or tablet that worked before cannot reach your agents now.

Cause: Someone removed the device in Settings → Devices → Paired devices. Its credential does not work now. This is correct behavior.

Fix:

• Android: Open Settings → Devices in Desktop. Click Show QR code and scan the new QR code with the phone.
• iOS: In the app, open Settings and tap Disconnect & Forget. Sign in again and select the HQ in the list. You do not need a QR code.

Problem: When you sign in to the web app in a new browser, it shows Approve this device, a QR code and this text:

Waiting for approval — scan this code with the dashsquad app on your phone.

Then it shows one of these messages:

Approval declined. You can try again from the HQ list.
The code expired. Try again from the HQ list.

Cause: This screen shows when an iOS app is already signed in to your account. That iOS app must approve the new browser. Approval declined means that someone tapped Deny on the phone. The code expired means that nobody approved it in the time limit.

Fix:

1. Go back to the HQ list and sign in again to get a new code.
2. On the phone, open the iOS app.
3. Open Settings → Approve a device.
4. Scan the code before it expires.

Problem: You scan a browser approval code in Settings → Approve a device. The iOS app shows this message:

This code has expired. Ask the device to try again.

Cause: Approval codes expire some minutes after the browser makes them.

Fix: On the browser, go back to the HQ list or sign in again to get a new code. Scan the new code immediately. For a valid code, the app shows Allow "<device>" to access <HQ>?. Tap Approve or Deny.

Problem: You deployed or added a remote HQ, but Desktop still shows the agents on this computer.

Fix:

1. Open Settings → General and look at the HQ section.
2. If the status shows This computer, click Change HQ.
3. Select Connect existing HQ.
4. Click Test connection, then click Use this HQ.

To go back to the local HQ, click Use this computer.

Problem: The HQ section in Settings → General shows an error for the remote HQ.

Fix: Make sure that the management URL is reachable and that the management token is correct. Also make sure that the relay credential is still valid. Click Change HQ and click Test connection again before you use the HQ. For a VPS deployment, connect to the server with SSH and run this command:

systemctl --user status dash-gateway.service

Problem: Deploy and connect fails before Desktop saves the HQ.

Fix:

1. Open Settings → General, click Change HQ and select Self-host on a VPS.
2. Make sure that Host, User, SSH port and SSH key are correct.
3. Make sure that the VPS has git, node, npm and systemctl --user.
4. Make sure that Relay URL and HQ id are correct.
5. Click Deploy and connect again.

Problem: Desktop shows the agents, but chat messages stop or fail.

Fix: Open Settings → General, click Change HQ and select Connect existing HQ. Click Test connection again. The Chat URL must use wss:// for an HTTPS relay. It must point to the same HQ host as the Management URL.

Cause: The workspace path in the agent configuration is not the folder that you expect.

Fix: Look at the workspace path of the agent. The HQ makes the workspace folder when the agent starts a chat. If the path is wrong, the tools look in the wrong folder. Relative paths in tools start at the workspace folder.

Error:

Command timed out after 30 seconds

Cause: The bash tool has no default time limit. The agent set a time limit for this command, and the command took more time.

Fix: Tell the agent to use a longer time limit or to divide the job into smaller commands.

Cause: The bash tool keeps only the last 2000 lines or 50 KB of output. It uses the limit that it gets to first.

The tool saves the full output to a temporary file and tells the agent the path. The agent can then read the parts that it needs with the read tool. You can also tell the agent to send the output through head or tail, or to a file.

Error (from a browser_* tool):

No browser available. Open dashsquad Desktop → Settings → Browser to install one.

Cause: The HQ found no Chrome or Edge on its computer, and no managed browser is installed.

Fix: Do one of these:

• Install Google Chrome or Microsoft Edge. Then click Check again in Settings → Browser in Desktop.
• Click Download browser (about 190 MB) in Settings → Browser. When the download is complete, agents use it automatically.
• If your browser is in an unusual location, set BROWSER_EXECUTABLE_PATH to its path.

Refer to Browser.

Error:

A browser was found at <path> but did not start in time. Try again in a moment.

Desktop shows the same problem as this message:

We found <browser> at <path>, but it didn't start in time.

Cause: The browser is installed, but it did not start in about 15 seconds. Usually the computer is busy.

Fix: Wait a moment and try again, or click Check again in Settings → Browser. You do not have to download another browser. If the problem continues, click Download a browser anyway to give your agents a managed browser.

Problem: Desktop shows this message:

We found <browser> at <path>, but it stopped with an error: <error>

Cause: The browser is installed, but it stopped when the HQ started it. The message shows the last error line of the browser.

Fix: Open the browser on its own to make sure that it works. Then click Check again in Settings → Browser. If the browser does not work, click Download a browser anyway to give your agents a managed browser.

Problem: Settings → Browser or the Your agent needs a browser card shows an error and no progress bar.

Fix: The download is about 190 MB and needs an internet connection for all of that time. Make sure that you have a connection and click Try again. After the download, the HQ starts the browser one time to test it. If the test fails, the HQ discards the new download and keeps the browser that you had before.

Error:

profile "<name>" is in use by conversation "<conversation>"

Cause: A saved profile can be open in only one conversation at a time.

Fix: Tell the agent in the named conversation to close its browser. Or wait: a browser closes automatically after 15 minutes with no activity. The same message shows if you try to delete a profile that is in use. Refer to Browser.

Error:

this HQ is already running <n> browser sessions

Cause: The HQ sets a limit on the number of open browsers for all agents together. <n> is that limit. The default is 3.

Fix: Tell an agent to close a browser that it does not need, or wait until an idle browser closes. You can also set BROWSER_MAX_SESSIONS to a higher value, up to 10. Refer to Browser.

Error:

port <port> on this machine is not allowed

Cause: The browser cannot open the HQ ports on the HQ computer. This is correct behavior. Other local addresses work. Refer to Browser.

Problem: You click View browser, and the view shows No browser is open in this conversation.

Cause: The agent closed its browser, or the browser closed after 15 minutes with no activity. View browser can still show, because the chat knows that the conversation used a browser.

Fix: Tell the agent to open the browser again. Then open the view again.

Problem: You click View browser and see Live view is not available on this HQ.

Cause: Your HQ is older than your app, and it does not have the live view.

Fix: Update the HQ, then open the view again. If Desktop runs the HQ for you, update Desktop on the HQ computer. Then restart the HQ: click the dashsquad icon in the menu bar, click Quit dashsquad… and click Quit and stop HQ. Then open Desktop again.

Problem: In Desktop, a turn fails with this message when an agent opens a browser:

Update dashsquad: the HQ sent an unsupported chat frame

Cause: Your Desktop is older than the HQ. It does not know the message that the HQ sends when a browser opens or closes.

Fix: Update Desktop to the latest version. Your conversation is safe on the HQ.

Problem: The live view shows Agent is driving, and your input does not go to the page.

Cause: While the agent works, only the agent controls the browser. This is correct behavior.

Fix: Wait until the agent's turn stops and the view shows You have control. Or stop the turn. Refer to Browser.

Problem: A plugin that you installed does not show its skills or commands.

Fix: In Desktop, open Settings → Plugins and look at the status badge of the plugin:

• Disabled: the plugin is off. Click Enable.
• Error: the plugin did not load. The card shows the error. Usually the manifest is bad or a SKILL.md file is missing.

If you edit the files manually, make sure that ~/.dash/gateway/plugins/config.json has an entry for the plugin with "enabled": true. Refer to Plugins.

Problem: The MCP servers, hooks, bin/ executables or providers of a plugin do nothing, but the plugin is enabled.

Cause: A new plugin is enabled but not trusted. Its skills and commands work. Its code and credential components stay off until you trust it. This is correct behavior.

Fix: Click Trust on the plugin card. Read the list of components that will run, then confirm. Refer to Plugins.

Problem: /<plugin>:<command> does not work.

Cause: Plugin commands have the plugin name as a prefix. For a plugin named research with commands/triage.md, the command is /research:triage, not /triage.

Fix: Make sure of these items:

• You type the full command with the plugin prefix.
• The plugin is enabled and shows Loaded in Settings → Plugins. Commands do not need trust.
• The file is in the commands/ folder of the plugin.

Fix: Update your HQ, then open the model picker again. The HQ gets a new provider list on the first request after six hours. It also gets a new list when its bundled catalog changes. In Desktop, use the refresh action to get the list immediately.

dashsquad selects the models that work well for chat and tools. A new model can need a catalog update before it shows. Free variants, batch variants and unreviewed previews do not show automatically. Make sure that you look under OpenRouter. A model from a direct provider is a separate entry.

If OpenRouter is not available, dashsquad keeps the last good list. It tries again when you open the picker after five minutes.

Problem: A model from the LLM provider of a plugin does not show in the model picker of the agent, or you cannot select it.

Cause: A plugin provider needs two things. The plugin must be trusted, because the HQ hides the provider catalog of an untrusted plugin. You must also add an API key for the provider.

Fix: Trust the plugin. Add the key in Settings → AI Providers. Then you can select the <id>/<model-id> models of the provider. Refer to Plugins.

Problem: The Install button or POST /plugins/install returned an error.

Fix: The response code tells you the cause:

Refer to Plugins.

Problem: A plugin that you removed still shows, or a plugin that you added manually does not show.

Cause: The HQ loads changes from Desktop and from the management API immediately. It does not watch the plugin folder for files that you add or delete manually.

Fix: After you edit ~/.dash/gateway/plugins/ manually, send POST /plugins/reload or restart the HQ.

When you remove a plugin, the HQ deletes its folder only if the management API installed it. The HQ does not delete a plugin that you added manually or a plugin with a path link.

Problem: An agent tried to start a sub-agent and got an error. The chat shows a red error block on the agent or spawn_worker call.

Cause: The agent got to a limit. The message tells you which limit:

Fix: If the job needs more sub-agents, increase the applicable limit in the subagents block of the agent. The change starts on the next message of the agent. Refer to Configuration.

The HQ limit has a default of 16. To change it, set SUBAGENTS_MAX_CONCURRENT_GLOBAL where the HQ runs. Then restart the HQ.

Error:

Agent would be spawned with zero tools: mcp__github, write

Cause: A sub-agent type asked for tools that its parent does not have. The result is a sub-agent with no tools, and dashsquad does not start it. The message shows the entries that gave no tools.

Fix: Do one of these:

• Give the parent agent those tools. In Desktop, open the Configuration tab of the agent and go to Tools. For mcp__… entries, assign the MCP servers.
• Change the tools: frontmatter of the sub-agent type to ask for tools that the parent has.

A sub-agent never gets a tool or MCP server that its parent does not have. Refer to Configuration.

Error:

depth limit reached (maxDepth 3) — an agent at depth 3 cannot spawn a depth-4 agent

Cause: A sub-agent can start its own sub-agents, but only to a limit. A direct child is at depth 1. The limit is subagents.maxDepth, with a default of 3.

Fix: Increase maxDepth for that agent, or do the work one level higher. An agent at the limit does not get the agent tool, so this error is rare.

Note in the tool result:

Note: alias "opus" is not configured (subagents.modelAliases); using the parent model

Cause: The model parameter of the agent tool accepts short alias names and full model IDs. The HQ finds aliases in subagents.modelAliases of the agent. No aliases are configured by default, because each provider uses different model IDs. The sub-agent then uses the model of its parent. Nothing failed.

Fix: Add the alias to subagents.modelAliases, for example {"opus": "anthropic/claude-opus-4-6"}. Or use a full provider/model ID or inherit. If the model is not the parent model or one of its fallbacks, also add it to subagents.allowedModels. Refer to Configuration.

Problem: A sub-agent asked a question with ask_orchestrator and showed the status waiting for input. Then it continued or stopped, and nobody answered. Its transcript shows ask_orchestrator aborted.

Cause: A question stays open only while the turn that started the sub-agent is active. When that turn stops, the HQ discards the open questions. A foreground sub-agent keeps the turn of its parent open until it stops, so you have time to answer. A background sub-agent usually continues after that turn stops, so nobody can answer its later questions.

Fix: Answer while the turn is active. If you expect the sub-agent to need a decision, start it in the foreground. For background work, tell the sub-agent in its brief what to do when it cannot ask.

Error:

isolation: worktree requires a git workspace

Cause: isolation: worktree gives a sub-agent its own checkout of the workspace, from the current commit. For this, the workspace must be in a git repository.

Fix: Run git init in the workspace of the agent, or point the agent at a folder that is a repository. Or remove isolation, so that the sub-agent uses the workspace of its parent.

Problem: A folder stays in ~/.dash/gateway/worktrees/<agent-name>/<subagent-id>/ after the sub-agent stopped.

Cause: The HQ removes a worktree only when it contains no work. It keeps a worktree that has uncommitted changes, untracked files or commits that no branch or tag keeps. Files that a build makes again do not count, for example node_modules/, dist/, build/, .next/, coverage/, *.log and .DS_Store. This is correct behavior.

The chat does not show the path. Use the template above with the ID of the sub-agent. Or look in the HQ log for a line with keeping, the path and the reason.

Fix: Look at the contents and keep or merge what you need. When the checkout is clean, run git worktree remove <path> from the parent repository. Git refuses while the checkout has changes. Commit or discard them first, or add --force if you are sure.

Problem: The HQ process stopped while sub-agents worked, for example after a crash, a force quit or a restart of the computer.

Recovery is automatic. When the HQ starts again, it marks each active sub-agent as interrupted and keeps its transcript. It then tells the parent agent in a notification turn. The rows in the chat show interrupted.

The HQ does not lose an interrupted sub-agent. To continue it, use one of these:

• Click Resume on its row in the tasks panel of the web app or in the tasks sheet of the iOS app.
• Send POST /subagents/:id/resume.
• Tell the parent agent to send it a message with send_message.

The sub-agent continues with its context. The HQ also removes orphaned worktrees at this time, but it keeps worktrees that contain work.

Problem: A resume returns an error. The resume can come from a row, from the tasks list or from send_message of the parent. A resume also counts against the limits for new sub-agents, so the limit messages above can also show here.

If a one-shot sub-agent is still active and asks a question, you can answer it. An answer is not a resume.

A resume gives the sub-agent only the tools and MCP servers that its parent has now. The HQ does not tell you if the sub-agent lost tools. The HQ does not examine the model again, so the sub-agent keeps its original model.

In Desktop, the Sub-agents panel disables Resume for a sub-agent that stopped. To resume it, use the tasks panel of the web app or POST /subagents/:id/resume. Refer to Configuration.

A sub-agent is a conversation, so its transcript is in the same location as other conversations:

~/.dash/gateway/sessions/<agent-name>/<subagent-id>/

To read it in the app, expand the row of the sub-agent in the chat, or open it from the tasks panel. The HQ never deletes transcripts automatically.

Older versions kept workers in ~/.dash/gateway/sessions/<agent-name>/.swarm/<runId>/. The HQ does not write to these folders now and does not delete them. You can delete them manually to get the disk space back.

Problem: You chat with an agent in Telegram or WhatsApp and see only the final answer.

Cause: Sub-agent rows and task panels are features of Desktop, the web app and the iOS app. Telegram and WhatsApp get only the final response of the agent. This is correct behavior.

Fix: To watch and control sub-agents while they work, chat with the agent in Desktop, the web app or the iOS app.

The provider session JSONL file keeps the model context. It is separate from the conversation that Desktop and paired phones show. After a crash, the file can have a bad line. The agent then cannot load its model context, but you can still see the conversation history.

Fix:

1. Open the folder ~/.dash/gateway/sessions/<agent-name>/<conversationId>/.
2. Open the .jsonl file in a text editor.
3. Remove or correct each bad line. Each line must be a valid JSON object.
4. Restart the HQ. In Desktop, click Restart HQ in Settings → General.

The HQ only adds lines to the end of the file. You can remove bad lines at the end with no damage to earlier context. This does not change the messages that the apps show.

To reset the provider session of one conversation, delete its session folder:

rm -rf ~/.dash/gateway/sessions/<agent-name>/<conversationId>

To reset all provider sessions:

rm -rf ~/.dash/gateway/sessions

Desktop keeps its data in ~/.dashsquad. Each HQ that Desktop starts has its own folder, ~/.dashsquad/<hq id>/. When Desktop starts the first time after the update, it moves your data from ~/.dash one time:

Desktop also changes the workspace paths in agents.json to the new folder. Your credentials, agents and conversations move with the HQ. The remote access identity of the HQ also moves. You do not have to set up remote access again, and your phones stay paired.

Desktop writes the file ~/.dash/MOVED-TO-DASHSQUAD.txt before it moves the data. The file contains this text:

Your DashSquad data moved to <path> on <time>.

<path> is the new HQ folder. If the move stops before it is complete, Desktop continues the move into the same folder when you click Try again.

Desktop does not do this move in these conditions:

• You set DASHSQUAD_HOME, MC_DATA_DIR or DASH_HOME.
• An older HQ still runs on ~/.dash. Desktop then shows Your HQ did not start. Refer to Desktop start.

A standalone HQ does not do this move. It continues to use ~/.dash/gateway/.

Older versions of dashsquad kept data in other locations. Before the move to ~/.dashsquad, dashsquad moves data from these locations into ~/.dash:

• macOS: ~/Library/Application Support/dash and ~/Library/Application Support/dash-gateway
• Linux: ~/.local/share/dash and ~/.local/share/dash-gateway
• Agent workspaces: ~/dash-workspaces

This move occurs only for data that is not already in ~/.dash. If you set DASH_HOME, dashsquad does not do this move. If you cannot find something, look in the old locations. You can copy the data that stays there manually. To use a different location for Desktop, set DASHSQUAD_HOME. For a standalone HQ, set DASH_HOME.

Cause: The HQ keeps all data in DASH_HOME. If that path is not on a persistent volume, the data stays in the container.

Fix: Set DASH_HOME to a path on a persistent volume, for example in docker-compose.yml:

environment:
  - DASH_HOME=/data
volumes:
  - dash-data:/data