AITroubleshooting
Troubleshooting AI apps
Fixes for the problems people hit most when connecting an AI app to Orbits.
Find the message you see, then follow the fix.
The browser did not open
Some apps open the approval page only when you ask them to sign in.
- Claude: in Settings › Connectors, press Connect on the Orbits connector.
- ChatGPT: open the connector in Settings › Connectors and connect it. If you don't see Create, turn on developer mode under Advanced.
- Claude Code: run
/mcp, choose orbits, then sign in. - Codex: run
codex mcp login orbits. - Cursor: in Cursor's MCP settings, press Connect next to orbits.
- VS Code: start the orbits server when VS Code asks.
- Windsurf: refresh Windsurf's MCP servers.
- Gemini CLI: restart it. It finds the sign-in on its own on first use.
- Over SSH or a remote desktop: the browser opens on the machine running the app. Sign in there, or run the server locally with a token.
"This connection request can't be used"
The app sent a request Orbits can't trust: an ID Orbits didn't issue, or an address to send you back to that the app never registered. Nothing was sent to the app. Remove Orbits from the app, add it again, and start over.
"Start from your AI app"
The approval page has no connection waiting. Requests expire after ten minutes. Go back to the app and connect Orbits again.
The page says only owners and admins can connect
An AI app acts for a team with an API token, and only a team's owners and admins can create one. Ask an owner of your team to make you an admin, or create a team of your own, then connect the app again. See Teams and roles.
"That's a lot of approvals in a minute"
You approved too many connections in a short time. Wait the number of seconds it says, then try again.
It worked, then started failing
If the app says Orbits did not accept the API token, the connection expired (after 30 days, 90 days or a year) or someone revoked it. Nothing is wrong with your account.
Reconnect the app: remove the Orbits server and add it again, or use the app's sign-in action above, and approve it again in the browser.
For Grok and the local server, the API token it uses expired or was revoked. Make a new one under Team › Settings › API tokens, or run orbits login again.
The token is read-only
The app was connected with Read only, so it can't change anything or read a variable's value. Either:
For the local server, use a full-access token.
Orbits refuses this to API tokens
Some things no API token can do, by design: managing tokens and members, billing, integrations, and deleting the team. Do them in the web app at orbits.africa. What an AI app can never do.
The team's plan does not include this
The tool needs a feature of the Pro plan, such as Analytics or Speed Insights. Nothing was changed. An owner can upgrade under Team › Billing in the web app. See Plans.
Not found
Check the project's slug or the deployment's id: ask the app to list them first. Not found also means it isn't in the connection's team, or, for a token limited to one project, isn't that project.
Too many requests
The app sent requests faster than its limit allows. The error says how long to wait. Wait that long, then ask again. Asking for fewer things at once helps, for example "list my projects" instead of one project at a time.
The app says a confirmation was not valid
Tools that delete, change production, change DNS or show a secret ask first. The confirmation_token in the preview lasts 5 minutes, works once, and works only for that exact request. If it has expired, was already used, or the app changed any detail, nothing is done. Ask the app to start again, check the new preview, then say yes.
The build is still running
Tools wait up to about a minute for a build or a change. If it is still going, the app gets the deployment's or operation's id and should carry on with wait_for_deployment or wait_for_operation. Ask it to keep waiting, or follow the build with orbits logs -f in the CLI.
A new variable isn't used
Environment variables apply to deployments built after you change them. Ask the app to redeploy, which asks first if it changes production.
The app can't deploy a folder
Only the local server can deploy a folder from your computer (deploy_folder), and only to an upload project. A Git project deploys from its repository: push, or ask the app to deploy a branch.
The local server will not start
orbits-mcp: command not found: installorbits-mcp, and make sure it is on yourPATH.orbits mcp statustells you if it is found.- No token found: run
orbits login, or setORBITS_TOKEN. - Wrong team: set
ORBITS_PROFILEto the CLI profile you want, orORBITS_TEAM. - It refuses the CLI's settings file: the file can be changed by other users on the computer. Make it yours only, for example with
chmod 600.
Orbits could not do this just now
A temporary problem on the Orbits side. Try again in a moment. If it keeps happening, contact support.
Still stuck
Every error from Orbits includes a request id. Contact support and include it.