Troubleshooting

The app will not open

Builds are not yet code-signed, so your system blocks the first launch.

• macOS: right-click the app and choose Open.
• Windows: in the SmartScreen prompt choose More info, then Run anyway.

"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.

"install failed" on a project

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

• Node.js is missing or too old. Install Node.js 20 or newer, then restart Graspable so it sees the new install.
• No internet connection. Packages are downloaded during install.

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 after installing Node.js 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. Without Node.js, or 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.

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.
• "skipped: no Chrome, Edge or Chromium found" — install one of those browsers. 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.

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

Still stuck

Tell us on Discord. Include the app version from Settings → Updates and the text of the error.