> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.orbitdev.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Common Orbit Issues

> Step-by-step recovery for startup errors, sign-in problems, chat failures, billing issues, desktop updates, and other common symptoms in Orbit.

If Orbit behaves unexpectedly, start with the symptom below and follow the recovery steps. For issues that persist after the steps here, use the general recovery checklist and contact support at [https://www.app.orbitdev.org/support](https://www.app.orbitdev.org/support).

## What to do when something fails

<Steps>
  <Step title="Check your connection and reload">
    Check your internet connection and reload the page or restart the app.
  </Step>

  <Step title="Confirm sign-in details">
    If sign-in fails, confirm the email, password, and verification or MFA steps.
  </Step>

  <Step title="Retry the action">
    If an AI request fails, retry once after checking the selected model and attachment.
  </Step>

  <Step title="Check plan and permissions">
    If a feature says it is unavailable, check your plan and account permissions. Not every feature is enabled for every account.
  </Step>

  <Step title="Contact support">
    For repeated errors, note the screen and approximate time, then contact support. Do not send passwords, private codes, secret keys, or full payment details in a support request.
  </Step>
</Steps>

## Symptom index

<Accordion title="I cannot create an account">
  1. Confirm that the email address is valid and that the password meets the current form's requirements.
  2. Check whether the Terms and Privacy checkbox is selected.
  3. If the message says an account already exists, use sign-in or password recovery rather than registering again.
  4. If registration reports a generic failure, retry once after checking connectivity. If the issue persists, contact support with the redacted message and time.
</Accordion>

<Accordion title="Verification email not arriving">
  You created an account but did not receive the verification email.

  1. Confirm that you entered the correct account email.
  2. Check your spam, junk, and filtered folders.
  3. Wait briefly before requesting another reset email.
  4. Use only the latest reset link; expired or already-used links may no longer work.
  5. If the mailbox is inaccessible, contact support for the approved identity-verification process.
</Accordion>

<Accordion title="The app could not start safely">
  This appears when the app is missing required public configuration, such as the Supabase URL and publishable key.

  1. Refresh the page once.
  2. If the message returns, confirm you are using the official app URL at [https://www.app.orbitdev.org](https://www.app.orbitdev.org).
  3. Try a different browser or clear the browser cache.
  4. If the problem persists, contact support with the time, timezone, and browser version.
</Accordion>

<Accordion title="The website could not finish loading / Orbit startup error">
  This is a runtime startup failure, often caused by a network issue or a browser compatibility problem.

  1. Refresh the page.
  2. Try the Open Sign In option if one appears.
  3. Check that your browser is up to date.
  4. If the error repeats, note the time and browser version and contact support.
</Accordion>

<Accordion title="Sent to /auth unexpectedly (authentication loop)">
  You tried to open a protected page and were redirected to sign-in, or you keep landing back on authentication after signing in.

  1. Sign in with your credentials.
  2. If you are asked for an MFA challenge, complete it.
  3. After signing in, the app should return you to the page you wanted.
  4. If you keep being redirected after signing in, confirm that the browser allows the app's necessary session storage and that the network can reach the backend.
  5. Check your device clock and network connection, then try a fresh app tab.
  6. If the loop persists, contact support with the route and approximate time.
</Accordion>

<Accordion title="Uplink Error toast">
  This toast indicates a query or network error, often temporary.

  1. Check your internet connection.
  2. Wait a moment for the service to recover.
  3. Refresh the page and retry the action.
  4. If the error repeats, contact support with the route you were on and the time it occurred.
</Accordion>

<Accordion title="Access code could not be redeemed">
  The code you entered was not accepted.

  1. Re-enter the code carefully, checking for typos.
  2. Confirm the code is still valid and intended for your account.
  3. Check your account entitlements in settings to see whether the feature is already active.
  4. If you are unsure, contact support with the code type and approximate time of the attempt. Do not share the full code in public channels.
</Accordion>

<Accordion title="MFA setup or verification is failing">
  Your authenticator code was not accepted or you cannot complete MFA enrollment.

  1. Use the current six-digit code from the authenticator, not an older notification or text.
  2. Check that the device's date and time are set automatically.
  3. For setup, scan the QR code or enter the secret only into the authenticator app, then complete the verification step.
  4. Do not send MFA codes, QR images, or setup secrets to support.
  5. If the enrolled device is lost, use the official recovery procedure or contact support.
</Accordion>

<Accordion title="Chat or provider unavailable">
  The chat interface does not respond or shows a provider error.

  1. Check your network connection.
  2. Shorten the prompt, remove an unsupported attachment, or select an available model.
  3. Wait briefly and retry the message once if no duplicate response or task is already running.
  4. If the problem repeats, contact your workspace admin or support.
  5. Include the model or provider you were using, the screen, time, and a redacted error in the support request. Never send the content of a secret file as a diagnostic.
</Accordion>

<Accordion title="A model, mode, or tool is locked">
  A lock indicator appears when the account cannot use a mode or tool.

  1. Review the Plans and pricing and Capabilities sections in Settings.
  2. Some tools depend on plan, redeemed access, platform, or staff role.
  3. Ask the account owner or support to confirm eligibility.
  4. A lock is an access control, not a prompt to bypass the UI.
</Accordion>

<Accordion title="Upload or source failed">
  A file upload or source attachment did not complete.

  1. Check your connection and file size.
  2. Retry the upload only if no duplicate already exists.
  3. If it fails again, try a different file format or contact support with the file type and route you were on.
</Accordion>

<Accordion title="Billing session or webhook failure">
  A payment or billing action did not complete or your plan was not updated after purchase.

  1. Do not repeat the purchase immediately.
  2. Reload the billing or settings page.
  3. Verify your payment method status with your provider before retrying.
  4. Check whether checkout completed and review the provider's billing portal or receipt.
  5. If the charge exists but Orbit does not reflect it, send support a transaction date and redacted reference. Never send card details.
  6. Contact support with the time and any transaction reference shown.
</Accordion>

<Accordion title="Workspace list is empty">
  No workspaces appear in the workspace switcher or library.

  1. Try **Everything** in the library and clear the search query.
  2. Verify the selected workspace.
  3. Sign out and sign back in.
  4. Ask your workspace admin to confirm your membership.
  5. If expected content is still missing, contact support with your account email and the time you noticed it. Do not create duplicate records as a test.
</Accordion>

<Accordion title="A workspace invite is rejected">
  The invitation token you entered was not accepted.

  1. Check for leading or trailing spaces and confirm the token came from the correct workspace owner.
  2. The invite could be expired, revoked, or already used.
  3. Request a new invite rather than sharing the old token more widely.
</Accordion>

<Accordion title="Desktop update error or Pro Pulsar cannot open">
  The desktop app fails to update or cannot open the Pro Pulsar feature.

  1. Keep the current app open.
  2. Retry the update or open action later.
  3. Make sure you are on a supported release channel.
  4. If the issue persists, contact support with your app version and operating system.
</Accordion>

<Accordion title="Desktop or mobile feature differs from the browser">
  A capability works in the browser but not on desktop or mobile.

  1. Check that you installed an official, current build.
  2. Review the platform limitations. Desktop bridge actions require Electron; mobile permissions are controlled by the OS.
  3. If a feature appears in documentation but not the installed product, ask the product team whether it is supported in that release.
</Accordion>

<Accordion title="Permission denied on a protected operation">
  You tried an action and received a permission error.

  1. Confirm you are signed in to the correct workspace.
  2. Verify your role with your workspace administrator.
  3. If your role should allow the action, contact support with the route, action, and time.
</Accordion>

<Accordion title="My conversation link does not open a specific chat">
  Conversations are addressable by URL at `/chat/:conversationId`. If a link does not open the expected chat, try these steps:

  1. Confirm you are signed in to the correct account.
  2. Open the conversation from the History page at [https://www.app.orbitdev.org/history](https://www.app.orbitdev.org/history).
  3. Select the thread you want to continue.
  4. If you need to share context, export or copy the relevant content manually.
</Accordion>

<Accordion title="How to report a bug">
  When something is not working as expected, include the following in your support request:

  1. The platform (browser, desktop, or mobile).
  2. The screen or route where the issue occurred.
  3. Approximate local time and time zone.
  4. Steps to reproduce, expected result, and actual result.
  5. A redacted error message if available.

  Do not attach raw environment files, access tokens, account recovery links, payment details, or unredacted user data.
</Accordion>

## General recovery checklist

Before contacting support, collect the following details:

* The route or page you were on
* The local timestamp and timezone
* The app version or platform (web, desktop, mobile)
* The operation you were trying to perform
* Any redacted error identifier shown in the UI (do not share access tokens or personal data)

Refresh once for transient read errors. Before repeating a write, payment, deletion, or device action, check whether it already completed.

## What to send support

When you open a ticket at [https://www.app.orbitdev.org/support](https://www.app.orbitdev.org/support), include:

* A clear description of the symptom
* The steps you already tried from this page
* The route, timestamp, timezone, and platform
* Any non-sensitive error identifier shown

Do not include access tokens, passwords, stack traces, or personal records in your message.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.