OrbitsDocs
esc
    Open Orbits
    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:

    • do it yourself in the web app or the CLI, or
    • reconnect the app with Full access. Access.

    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: install orbits-mcp, and make sure it is on your PATH. orbits mcp status tells you if it is found.
    • No token found: run orbits login, or set ORBITS_TOKEN.
    • Wrong team: set ORBITS_PROFILE to the CLI profile you want, or ORBITS_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.

    Was this page helpful?

    Updated