Banata

Platform

Troubleshooting

Common issues when using the Banata API and how to resolve them.

This page covers the most common issues you may encounter when using Banata and how to resolve them.

Browser Sessions

Session stuck in queued

Symptoms: The session stays in queued for more than 30 seconds.

Causes:

  • All machines in your preferred region are at capacity.
  • A new machine needs to be created, which takes longer than usual.

Solutions:

  • Continue polling — the platform retries scheduling automatically.
  • Try without specifying a region to allow any region.
  • Check the health endpoint (GET /health) to see if machines are running.

Session stuck in assigning

Symptoms: The session moves to assigning but does not reach ready.

Causes:

  • The worker is still setting up the browser context (stealth fingerprint, profile loading, etc.).
  • The machine had a transient issue during setup.

Solutions:

  • Wait up to 10 seconds — this state is usually brief.
  • If it persists, end the session with DELETE and create a new one.

CDP connection refused or times out

Symptoms: Puppeteer or Playwright cannot connect to the cdpUrl.

Causes:

  • The session is no longer in ready or active state (it may have ended or failed).
  • The JWT token in the URL has expired (tokens are valid for 1 hour).

Solutions:

  • Re-check the session status with GET. If the status is ended or failed, create a new session.
  • If the session is still active, get fresh status (the cdpUrl doesn't change, but verify the session is alive).

browser.newPage() not working

Symptoms: Target.createTarget error when calling browser.newPage() in Puppeteer.

Cause: Each Banata session provides a single pre-configured page. Creating additional pages is not supported.

Solution: Use the page that comes with the session:

typescript
const page = (await browser.pages())[0];

If you need to work with multiple pages at the same time, create multiple sessions — each one runs independently.

Stealth not working — bot detected

Symptoms: Target site detects automation even with stealth: true.

Causes:

  • The site uses behavioral analysis (mouse patterns, timing) in addition to browser fingerprinting.
  • Datacenter IP addresses are blocked by the target site.

Solutions:

  • Add realistic delays between actions (await page.waitForTimeout(random(1000, 3000)))
  • Use residential egress: egressProfile: "rotating-residential" (Scale plan) or BYO residential proxy
  • Reuse browser profiles with profileKey to build cookie history
  • Combine all three for the strongest anti-detection posture

Sandboxes

409 Sandbox is not ready

Symptoms: Exec, code, or file system requests return 409.

Cause: The sandbox is still in queued or assigning state.

Solution: Poll the session status until it reaches ready before sending any execution requests:

typescript
let sandbox;
do {
  sandbox = await fetch(`https://api.boxes.banata.dev/v1/sandboxes?id=${id}`, {
    headers: { Authorization: `Bearer ${apiKey}` },
  }).then(r => r.json());
  if (sandbox.status === "failed") throw new Error("Sandbox failed");
  if (sandbox.status !== "ready" && sandbox.status !== "active") {
    await new Promise(r => setTimeout(r, 1000));
  }
} while (sandbox.status !== "ready" && sandbox.status !== "active");

Sandbox commands hang or timeout

Symptoms: POST /v1/sandboxes/exec takes very long or times out.

Causes:

  • The command itself takes a long time (large npm install, heavy build).
  • The command is waiting for interactive input (e.g., a prompt).

Solutions:

  • Set a timeout in the request body.
  • For interactive programs, use the terminal WebSocket instead of the exec endpoint.
  • For package installs, consider pre-baking dependencies in the workspace.

Files not found after pause/resume

Symptoms: Files in /tmp or outside /workspace are gone after resuming a paused sandbox.

Cause: Only the /workspace directory is preserved across pause/resume cycles.

Solution: Keep all important files in /workspace. Use checkpoints for additional persistence guarantees.

Plan and Billing Issues

403 PLAN_FEATURE_UNAVAILABLE

Symptoms: Session creation fails with a 403 error mentioning plan requirements.

Cause: The feature you requested (stealth, recording, dedicated isolation, heavy weight, residential egress, large sandbox, paired browser) is not available on your current plan.

Solution: Either:

  • Remove the feature flag from your request (e.g., set stealth: false)
  • Upgrade your plan via POST /v1/billing/checkout

The error response tells you exactly which plan you need:

json
{
  "code": "PLAN_FEATURE_UNAVAILABLE",
  "requiredPlan": "pro",
  "currentPlan": "builder"
}

429 Monthly browser hours limit reached

Symptoms: New session creation fails even though you are below your concurrent limit.

Cause: Your organization has used all its monthly browser hours.

Solution:

  • Check usage with GET /v1/usage
  • Wait for the billing period to reset (1st of the month)
  • Upgrade to a plan with more browser hours

429 Rate limit exceeded

Symptoms: Requests return 429 intermittently.

Solution: Check the Retry-After header and wait that many seconds before retrying. The @banata-boxes/sdk handles this automatically. See Rate Limits for per-endpoint limits.

Authentication Issues

401 Invalid or missing API key

Checklist:

  • Authorization: Bearer br_live_... header is present (not Authorization: br_live_...)
  • The key starts with br_live_
  • The key has not been revoked in the dashboard
  • The key has not expired
  • There are no extra spaces or newlines in the key value

Getting Help

If your issue is not covered here:

  1. Check the API Reference for exact request/response formats.
  2. Check the health endpoint (GET /health) to verify the platform is operational.
  3. Contact support through the Banata dashboard.

Next Steps