# Troubleshooting

> Fixes for common problems with installing, project setup, the preview, sign-in, checks, headsets and cloud agents.

Source: https://graspable.dev/docs/troubleshooting

## The app will not open

The macOS app is signed and checked by Apple. If macOS still refuses to open it, the download is probably incomplete: delete it, download it again from [graspable.dev/download](https://graspable.dev/download) and compare its checksum with the one on the download card.

## "agent unavailable" on the Projects page

The agent that runs beside the app did not start. Quit Graspable fully and open it again. If it keeps happening, install the latest version from [graspable.dev/download](https://graspable.dev/download).

## "install failed" on a project

Creating a project installs its packages. The project list shows the last line of the error.

- **No internet connection.** Packages are downloaded during install.
- **You chose your own Node.js** under Settings → Components → Advanced, and it is older than version 20. Update it, or switch back to **Built into Graspable**.

A failed install does not lock the project. You can still send a request, for example to ask the agent to fix `package.json`. The simplest fix is to create the project again.

## The preview does not start or is empty

- **Preview** and **Split** are disabled while packages are installing. Wait for "installing deps" to disappear from the header.
- If starting fails, a red bar under the header shows the reason. After a failed install the preview cannot start.
- If the preview stops responding, use the round-arrow button. It restarts the dev server if needed.
- If the preview area stays empty in an older version, update. Version 0.9.15 fixed a blocked preview in the installed app.

## A sign-in did not finish

- **"No model account yet".** The Graspable agent has no sign-in or key. Open **Settings → AI for the agent**.
- **The browser did not open.** Choose **Browser didn't open? Open the sign-in page** or **Open the sign-in page again**.
- **ChatGPT.** Choose **Not working? Use a code instead** and enter the code shown on the page that opened.
- **Claude.** If the page shows a code, paste it into the field in Settings.
- **Graspable account.** Open the email link on the same computer. If the email shows a code, type it into the field.
- **"ChatGPT sign-in has ended"** or **"Claude is not signed in, or the session expired".** Sign in again in Settings.

Choose **Cancel** to start over. You never need a terminal to sign in.

## Old changes or approvals reappear after a connection interruption

The next desktop update fixes repeated file updates and answered approval cards after a run reconnects. It also keeps late responses from appearing in a different conversation. Updated agents resume after the last received update instead of sending the whole conversation again; cloud projects need the updated Cloud Agent as well. If you see this in an older version, reopen the project to load its saved conversation and files.

## The conversation stops updating after opening history

The next desktop update keeps the current conversation live if another conversation cannot load. Slow history requests also stop replacing a newer selection. If you switch conversations while a new request is still preparing, that preparation will not start an agent run. Requests already accepted by the agent continue until they finish or you cancel them.

## Typing feels slow in a long conversation

The next desktop update avoids redrawing unchanged responses as you type. Your full conversation remains available to read. Switching conversations also closes feedback forms from the previous conversation.

## A conversation cannot reconnect

In the next desktop update, a connection error offers **Retry** above the conversation. Retry loads that same run and checks its current state; it does not submit your prompt again. A failed history load leaves the visible conversation available. If a run was interrupted, retry can continue it after reconnecting. Your unsent text stays in the prompt box. If the conversation list itself could not load, Retry checks that list again and opens the latest conversation. A successful empty history is not treated as an error.

## A request could not be sent

In the next desktop update, a failed or abandoned submission keeps your prompt and selected code so you can try again. If Graspable says the request **started** but its updates could not open, use **Retry** to reconnect instead of sending the same request again. Text you type while a previous request is being sent stays in the prompt box. Code you select during that wait stays selected for your next request; only the selection sent with the accepted request is cleared.

## A check keeps failing

After three repair turns the run stops and names the check.

- **build** — read the error in the transcript. Tell the agent what you see, or undo the run.
- **smoke** — look at the screenshot under the check. It shows what the browser saw.
- **xr … differ from the recording** — the scene changed. If you meant it, choose **Accept new baseline**. See [XR tests](https://graspable.dev/docs/xr-tests.md).
- **"skipped: there is no browser to load the scene in yet"** — open **Settings → Components**. It shows the browser download, or **Try again** if it failed. Interrupted or oversized downloads are discarded; a stalled download stops with an error instead of waiting indefinitely. The build check still runs.

## "The recording is empty"

An XR recording has no movement in it. This happens when the app crashed in XR while it was being recorded. Record it again, or delete the file from `tests/xr/`.

## The run stopped by itself

- "budget" — the run crossed a cap in **Settings → Run budget**.
- A ⚠ line about a loop or repeated failures — the agent was stuck. Rephrase the request or split it into smaller steps.
- "continuing after the restart" — the app restarted while the Graspable agent was working (an update, a crash, a forced quit). Nothing is lost: the run goes on from its last step as soon as you open the project. It asks again for anything it was waiting on. A run of Claude Code or the Codex CLI cannot be continued this way and is closed as failed.

## Voice

- **"Graspable may not use the microphone"**: allow Graspable to use the microphone in your system's privacy settings, then try again.
- **"No microphone was found"**: connect a microphone or turn one on, then press the button again.
- **"The microphone is in use by another app"**: close the app that holds it, or end the call, then try again.
- **"Nothing was heard"**: speak a little closer to the microphone. A press shorter than half a second is ignored.
- **"Sign in to your Graspable account to use voice"**: sign in under **Settings → Graspable account**, or add your own ElevenLabs key under **Settings → Voice**.
- **"ElevenLabs did not accept the key"**: check the key under **Settings → Voice**.
- **"Today's free voice is used up"**: voice beyond the free minutes uses Credits. Add Credits, or use your own ElevenLabs key. See [Credits](https://graspable.dev/docs/credits.md).
- **"The recording is too long"**: one recording holds a few minutes of speech. Say the request in shorter parts.
- **The words come out in the wrong language**: choose the language you speak under **Settings → Voice**.
- **The button in the headset says "Reconnect voice from Graspable"**: allow the microphone in the headset's browser. Then choose **Talk in the headset** again in the app and scan the new code.

See [Voice](https://graspable.dev/docs/voice.md).

## Headset

- **"No network connection"** or the link does not load — put the computer and the headset on the same Wi-Fi, or use USB. If the panel offers several addresses, try another.
- **The headset warns that the connection is not private** — expected the first time. Choose **Advanced**, then **Proceed**.
- **USB shows no headset** — install Android platform-tools (`adb`), turn on developer mode in the headset, plug it in, then allow USB debugging inside the headset.
- **Cloud project** — headset preview is not available. Move the project back to this computer.

## Cloud agents

| Message | What to do |
|---|---|
| "The cloud agent runs Graspable …, which this app cannot work with" | The Cloud Agent is from a much older version. Click **Cloud** in the project header and choose **Update the cloud agent** |
| "You have no Credits left" | Cloud Agents run on Credits. Buy a Credit pack, turn on overage, or choose a plan. See [Credits](https://graspable.dev/docs/credits.md) |
| "This template comes with the Builder plan and higher" (or "the Pro plan and higher") | Premium templates need a paid plan; the native XR ones need Pro. Sign in under **Settings → Graspable account** and go online once, so the app can check your plan |
| "You have used this month's … Credits" | Wait for them to renew, upgrade, or move the project back to your computer. See [Credits](https://graspable.dev/docs/credits.md) |
| "Cloud Agents are not ready for Graspable … yet" | Update the app, then try again |
| "The cloud agent is Graspable X and this app is Y. They must match" | Update the app, or the image or server, so both are the same version |
| "The cloud agent refused the token" | Your own server: check the **Agent token** in **Settings → Cloud Agents** |
| "The cloud agent did not start in time" | Try again. For your own server, check that it is running and reachable |
| "The cloud agent cannot be reached" when moving back | Choose **Wake now**, then try again |
| The header shows "not found" | The sandbox no longer exists. Choose **Restore the copy from before the move** |
| A run is refused in the cloud | Cloud runs need the Graspable agent with an API key |
| "… its cloud sandbox could not be deleted" | The project is safely back. Delete the sandbox in your provider's dashboard |

## Confirming an action

Deleting a project or capture, changing seats, and discarding animation or USD edits wait for your answer in a confirmation dialog. Choose **Cancel** to keep things as they are.

## Still stuck

Tell us on [Discord](https://discord.gg/Ta4EF7VuAs). Include the app version from **Settings → Updates** and the text of the error.
