Common errors

Desktop errors#

"Desktop failed to start"#

Your desktop stopped while it was starting, without a reason the page can name, and the desktop page says "Desktop failed to start. Try starting it again." It is usually a temporary infrastructure issue or a lack of resources on the host. A desktop with no account or API key does not end up here: it says "Agent did not start" instead.

Start the desktop again. If it fails twice in a row, email contact@spinestudio.dev.

Desktop limit reached#

Your workspace already has as many desktops as its plan allows. The create form shows "You have 1/1 desktops. Delete one or upgrade your plan." under the plans, with your own numbers, and its "Create desktop" button stays disabled.

Delete a desktop you no longer need, or upgrade the plan. Stopping a desktop does not free its place: a stopped desktop keeps its machine and its files, so it still counts.

"This desktop needs your own AI credential."#

The create form shows this when the agent you picked has no account or API key to run on yet, and its "Create desktop" button stays disabled until it has one. Under the message, the form offers what that agent can use: a "Connect a Claude account" or "Connect a ChatGPT account" link, "Paste an API key below.", or both.

Connect the account or paste the key, then create the desktop. A desktop that already exists and has lost its credential does not start: see "Agent did not start" below.

Agent errors#

"Agent starting up..."#

The agent has not finished starting, and the chat panel's header says so. It is the last service to come online, typically about 2 minutes after desktop creation.

Wait for the boot to finish. The chat panel enables automatically when the agent is ready. At the 3-minute mark the toolbar may show "Boot is taking longer than expected." That message alone is not a reason to restart. If the agent is still not ready 4 minutes after creation, stop and restart the desktop.

A Grok desktop is the exception: it waits for you to sign in with your xAI account, and its chat shows a "Sign in to Grok" card instead of this message. Sign in there and do not restart: a restart brings the same card back.

"Agent did not start"#

Your desktop is running, but its agent did not finish starting. A card above the chat's message box names the cause: "No account connected" or "No API key", "Account refused" or "API key refused", "Account quota reached", "API key quota reached" or "xAI quota reached", or "Agent could not start".

Use the card's button where it shows one. Agent not responding explains each card, what to do when it shows no button, and the errors that can replace a reply.

Rate limit reached#

You sent too many requests to the AI provider in a short period, and it is refusing more for now. Each provider sets its limits by your plan with it. After retrying for a while, the chat shows in place of the reply: "The AI model is currently rate-limited. Please try again in a minute, or switch to a different model." If the agent may already have received your message or started on it, part of the work may be done, and the chat shows this instead: "The AI model has reached its request limit for now, so the agent stopped before finishing this reply. The agent may already have received your message and done part of the work — check the desktop before sending it again. If you do, wait a minute first or switch to a different model."

Wait a minute before sending more messages, or pick another model from the chat's model menu. Free-tier API keys have strict limits. If you hit this often, consider upgrading your plan with the provider.

Connection errors#

Lost connection to a desktop#

Each panel of the desktop page has its own live connection, and says when it drops:

• Chat: "Not connected. New messages won't appear here until the connection is back.", with a "Retry" button.
• VNC viewer: it keeps the last picture it showed, and the line above it says "Disconnected" or "Connection error", then "Connecting to desktop..." while it reconnects on its own. With no picture to keep, it shows "Failed to connect to desktop" or "Desktop is disconnected", with a "Reconnect" button.
• Terminal: "Connection closed", with a "Reconnect" button.

If the connection does not come back:

1. Confirm the desktop status is running in the dashboard
2. Reload the page to open a new connection
3. Try a different browser or disable extensions
4. On a corporate network, test on a different network. A firewall can block the connection.

Desktop display issues covers the VNC viewer in more detail.

Quick troubleshooting checklist#

1. Is the desktop in running state? Many errors resolve once the boot finishes.
2. Is your API key valid and funded? Check on the provider's website.
3. Have you waited at least 4 minutes? The agent comes up last, usually about 2 minutes after creation.
4. Have you tried restarting? Stop the desktop, wait for stopped, then start it again. A Grok desktop showing a "Sign in to Grok" card needs your sign-in, not a restart.
5. Same error on multiple desktops? That points to a platform issue. Check SpineOS's social channels or email contact@spinestudio.dev.