Borealis Docs

Troubleshooting Borealis

Identify the resource and operation first. An uncertain response is different from a confirmed failure.

Sign-in succeeds but a request fails

Check the token’s target service, selected organisation, and granted permissions. API and MCP credentials are not interchangeable. A 403 can also result from ownership or plan restrictions, so requesting a broader token is not always the fix.

For CLI issues, run borealis auth whoami and borealis context show --json. Redact identity details before sharing output.

A sandbox will not start

Inspect the sandbox state and pending operation. Verify the image reference, registry access, target architecture, and startup command. Check available CPU, memory, slots, and host health.

For a basic Ubuntu environment, sleep with arguments ["infinity"] keeps the container alive. A command that exits immediately is not a long-running sandbox service.

If creation timed out, look for the returned sandbox or request ID and preserve the original idempotency key. Do not immediately submit a new creation with a new key.

A command disappeared or never finished

Inspect the execution ID, not only the sandbox logs. Check whether the sandbox stopped or the host restarted. Runtime loss can leave an execution unavailable.

Before repeating a command, consider whether it may already have changed external state. See commands and terminals.

A preview does not connect

Confirm that the service is listening on the expected container port and on an address reachable from outside its process namespace, usually 0.0.0.0. Check the port binding and use the returned gateway URL.

A healthy sandbox does not imply the application server is healthy. Read its output and startup configuration.

A snapshot or import is still pending

Keep its request or upload handle and query progress. A snapshot is usable after its operation succeeds; a completed upload still needs the import completion step.

If expected files are missing, check whether they belong to /workspace, the root filesystem, or a mounted volume. Review transfer policies and snapshot boundaries before assuming data loss.

A request is throttled or capacity is unavailable

Honour retry guidance, use backoff, and check account limits and host availability. Avoid parallel retries of the same mutation.

Ask for help with a useful report

Include the time and timezone, organisation context, sandbox ID, operation or execution ID, status, error code, and minimal steps to reproduce. Explain whether the issue occurs in the app, CLI, API, or MCP client.

Exclude tokens, secrets, enrollment commands, and private archive contents. Follow your account’s support channel; use vulnerability disclosure for security issues.