Skip to content

DocsProduction

Troubleshooting

Find what you see, then the cause and the fix.

Words such as Computer sandbox and binding are defined in Terms.

Error names are the Ruby SDK's (PineSandbox::…). TypeScript and Python name the lifecycle and project-key errors the same way with an Error suffix (InvalidClientKeyError, ProjectAccessDeniedError). A Computer's own problem responses, such as a busy or missing session or an expired access grant, are an ApiError in both: test its problem type, for example /errors/session-busy. In Go, match errors with errors.Is and errors.As. Failure handling has the full list.

Signing in and access

No sign-in email arrives

  • Only an approved address gets a sign-in link. An address on the waitlist gets its next step instead: the link to confirm the application, or, while it waits for review, the link to use an invite code.
  • Check your spam folder, then resend from the sign-in page after a minute. An address can ask for a sign-in link five times an hour; after that, wait and try again.
  • If nothing arrives after a resend, the address may not have access or an application yet. Sign in with the address you were approved with, or request access.

A sign-in link works once and expires after 15 minutes. Request a new one from the sign-in page, and open it in the browser you'll use the Console in. The link in your welcome email lasts longer, but works only once too; after that, sign in from the sign-in page. You never need to apply again.

A guide or SDK page says it's for approved accounts

Some guides and the SDK pages are for approved users. Sign in, and the page opens.

The Console says API access isn't on

Your project can use the Playground, but its keys can't create Computers yet. Select Ask Pine to turn it on on the project's Overview page.

Installing an SDK

pip install pinesandbox finds nothing

The Python SDK isn't on PyPI yet. Download it from its SDK page and add the wheel it holds, as Install shows.

An error says the package is a placeholder

You installed version 0.0.1, which only reserves the name. Install the latest release: npm install @pinesandbox/computer@latest (or @pinesandbox/computer-web@latest), or bundle update pinesandbox.

The TypeScript SDK throws as soon as it loads in a browser

@pinesandbox/computer holds your project key and Computer credentials, so it refuses to run in a browser. Keep it on your backend and show the desktop with @pinesandbox/computer-web (Web SDK).

The install fails on an older Ruby, Go, Node.js or Python

The SDKs need at least:

  • Ruby 3.3 for the Ruby SDK;
  • Go 1.23 for the Go SDK;
  • Node.js 22, or Bun, for the TypeScript SDK;
  • Python 3.10 for the Python SDK;
  • Node.js 20 to install and bundle the web SDK.

Creating or starting a Computer

InvalidClientKey

The project key is unknown or revoked, or its project is suspended or has API access turned off. Check that the key you deployed hasn't been revoked under the project's API keys in the Console, or create a new one.

ProjectAccessDenied

The key is valid but may not start a Computer now. error.reason says why:

  • spend_limit_reached: the project's organization is out of credits, or the project has reached its monthly spend limit; error.message says which. An owner or admin of the organization adds credits on its Billing page or raises the project's limit on its Usage and quotas tab. Computers already running keep going until their current access grant lapses, then answer 403 /errors/lease-expired.
  • api_access_disabled: ask Pine to turn API access on.
  • project_suspended or computer_disabled: contact Pine.

CapacityExceededError

The project is running as many Computers as it may, so nothing was created. Stop one you no longer need, or wait for an abandoned one to expire. Look for Computers your code didn't stop: the project page lists recent ones not yet recorded as stopped. Retrying at once won't help.

CreateRateLimitedError

The project started as many new Computers in the last minute as it may. Wait the number of seconds the error gives (retry_after in Ruby, retryAfterSeconds in TypeScript, retry_after_seconds in Python, RetryAfter in Go), then create or start again.

BindingRevisionConflictError

Another worker started this Computer first, or create_computer was called with the ID of a Computer that's already been started. Load the binding that worker saved and reconnect with it. Don't retry automatically: the Computer may be in use.

ComputerAlreadyStartedError

Start or Recover found the Computer already started: its current runtime is running, or pending, allocated or resuming on its way there. Nothing was started. Keep using it: reconnect with client.reconnect_computer and the binding you saved. To start over instead, stop it first, then start it. The error's state and reason say what the runtime reported. When Start waits or refuses lists every state.

SandboxRetainedError

Start or Recover found a Computer runtime it may not replace, and nothing was released or started. The error's state and reason say which. If state is failed, call recover_computer, or stop the Computer and then start it. With the reason CaptureTimeout (CAPTURE_TIMEOUT on later servers), recover_computer refuses until the capture settles; read its status again later. If it's paused or pausing, resume it, or stop it before you start again. When Start waits or refuses lists every state.

ReadyTimeoutError

ready_timeout (300 seconds by default) ran out while Start waited for the Computer's current runtime to be released or for the new one to be ready. The error names the runtime, the last state and reason it reported, and how long Start waited. Nothing was attached and the binding is unchanged. Back off according to the reason, for example COMPUTER_CAPACITY_UNAVAILABLE when no capacity was free, then start again. A Start right after a Stop of a paused Computer can need a larger ready_timeout.

UnknownComputerError

The ID was deleted, or belongs to another project. A new ID is registered by its first create.

AttachAuthorizationCommittedError

Pine authorized the attach, then the attach itself failed, for example because the Computer restarted during it. Record it as a failed attempt, keep the credentials, and call start_computer to start it again. Do this even when the call that failed was create_computer.

A create or start timed out

The outcome is unknown, and the Computer may be running. Stop it by ID with client.stop_computer(computer_id), then start it with its saved credentials: Start waits while the Computer finishes stopping. If the start raises UnknownComputerError, the first create never registered the Computer: create it again with the same saved credentials. Don't create a new Computer in its place.

While a Computer runs

ConnectionError or TimeoutError on a slow or distant network

The request got no answer: this process lost the network, not the Computer. A request whose connection couldn't be opened is sent again by the SDK, three attempts in all; a read is also sent again after a dropped connection. When the error still reaches you, don't stop the Computer because of it: a turn keeps running, so call wait again. If connections time out while being opened, for example behind a proxy whose TLS handshake takes seconds, raise the client's connect timeout (default 10 seconds) and request timeout (default 30 seconds): connect_timeout: and request_timeout: in Ruby, ConnectTimeout and RequestTimeout in Go, connect_timeout= and request_timeout= in Python. In TypeScript, set requestTimeoutMs, and the connect timeout on the fetch you pass (the SDK README shows one).

A rejected certificate or a host that doesn't exist arrives as a ConnectionError after the same three attempts as any other connect failure: check the endpoint and this machine's trusted certificates.

The Computer stopped on its own

A Computer with nothing to do is released timeout: seconds after its last activity, 300 by default. Running commands, driving the browser and agent turns count as activity, and a Computer keeps running while a person holds control of a session. Reads, event streams and status checks don't count, and neither does an open desktop after the person's control ends. A Computer also stops when it reaches its maximum age, seven days by default. Set timeout: for the work, and save state you need before it runs out. What keeps a Computer running lists what counts.

SandboxGoneError

The Computer can't be reached at its host, which is also true while it's paused or recovering. Read computer.status before you act, then follow what to do for each state.

ComputerStopped (409 /errors/computer-stopped)

A Stop has begun, whoever sent it, and the Computer refuses every call until it starts again. Retrying won't help. Read computer.status to follow the Stop, then start the Computer. Go errors match pine.ErrComputerStopped; TypeScript and Python test ProblemType.computerStopped and ProblemType.COMPUTER_STOPPED.

TokenRejectedError

The Computer no longer accepts this attach's Computer token. If the Computer is still running, another worker may have attached it since: check your records for a newer binding before you stop or replace anything. Start again only once the Computer has stopped.

LeaseExpired (403 /errors/lease-expired)

Pine stopped renewing this Computer's access, for example because the project was suspended, its organization ran out of credits, it reached its monthly spend limit, or the Computer was deleted. Reads, cancelling a turn and closing sessions still work, so you can wind down.

LeaseRefreshUnavailable (503 /errors/lease-refresh-unavailable)

Renewal is briefly unavailable. Retry the call; don't start the Computer again because of it.

SessionNotFound, or a session token is rejected

The session was destroyed, or the Computer has started again since: sessions don't survive a start. Create the session again and send it its inputs.

409 /errors/session-limit

The Computer runs as many sessions as it may. Destroy sessions you're done with; computer.capabilities (Ruby), computer.capabilities() (Python), computer.Capabilities(ctx) (Go) or computer.capabilities() (TypeScript) reports the limit.

Pine's agent

409 /errors/session-busy

A turn is already running in this session. Wait for it, steer it, or cancel it before you run again. Shell commands and tab calls still work meanwhile.

ControlNotHeld (409 /errors/control-not-held)

A person holds control of the session. Release control from your backend before you send the agent new work.

409 /errors/stale-turn

You answered a turn that's no longer the latest, or sent a different answer to one already answered. Read the turn again and answer the latest one.

RunUnconfirmedError

No response confirmed the run. Send it again with error.idempotency_key: you get the same turn, never a second one.

wait returns a turn that's still running

wait returns when the turn ends or its timeout: passes. A running turn isn't stuck: wait again, or cancel it. When the network was down until the timeout, wait returns the turn as it last read it.

The Computer stopped before a person answered the agent's question

Waiting for an answer doesn't keep a Computer running, and a start doesn't bring back the session or the question. Create a session, and run a new goal that includes the question, the answer and the inputs it needs. Next time, set timeout: long enough for a person to reply.

AgentProtocolUnsupported

The Computer was started on a release older than this SDK's agent protocol. Stop it and start it again to update it.

StreamLostError

An event stream couldn't reconnect. Resume from the last event ID you saved, with its task ID.

The desktop

The desktop doesn't connect, or drops when it reconnects

A desktop token lasts 120 seconds. Give the component a function that asks your backend for a new token, so it gets one for every connection and reconnection. The function has 20 seconds to return.

Keyboard and mouse input are ignored

The component starts in view mode, which sends no input. Take control of the session on your backend first, then switch the component to drive: setControl("drive") on <pine-desktop>, or control="drive" in React and Vue (Human in the loop).

Control went back to the agent while the person was using the desktop

Control ends at the control state's idle_deadline, 15 minutes after taking it, unless your backend extends it with update_control first. The person's typing and clicking don't extend it. Switch the viewer to view and take control again (Human in the loop).

Copy and paste don't work

The browser allows clipboard access only on a secure (HTTPS) page and after a user gesture. When a copy can't happen on its own, the component shows a copy panel the person can use. Keyboard, touch and clipboard covers the settings.

After a stop or a start

computer.stop returned false

The Computer didn't stop within the wait. By then the Stop was submitted, or the runtime was already shutting down. Call stop again on the same handle, or on one rebuilt from the saved binding. Until a release is confirmed, the Computer counts against your project's limit.

Tabs, sessions or files are missing after a start

That's expected. A start restores the Computer's sign-ins, localStorage, passkeys and learned skills, not its tabs, sessions or files. Download outputs before you stop, or keep them as artifacts, and create sessions again after a start. Persistence lists what comes back.

A site signs you out after a start

Cookies are restored on a best-effort basis, from the latest save. localStorage is saved when the browser stops, so stop the Computer with computer.stop rather than letting it expire. Call computer.checkpoint after an important sign-in to save cookies right away.

Artifacts

ArtifactStorageFullError

The Computer's artifacts have reached their limit, so upload or copy saved nothing. The error reports used_bytes and limit_bytes. Delete files the Computer no longer needs, then save again: deleting works while the artifacts are full. On the Computer, the agent's pine-artifact save refuses the same way, and pine-artifact rm makes room.

ArtifactNotFoundError

No file is at that path, for open, download, delete, or the source of a copy. Its path names the one it looked for. Paths are case-sensitive and have no leading /; list the folder with list to check.

An artifacts call answers 404 COMPUTER_NOT_FOUND

The Computer ID is unknown, belongs to another project, or was deleted. Pine issues no storage token for a deleted Computer's artifacts, even during the 25 hours before it deletes them. For a copy, the source must be a live Computer of the same project: this one or another.

Getting help

Reach Pine with Send feedback in the Console. Include:

  • the error's request_id, when it has one;
  • the Computer ID, session name and turn ID;
  • when it happened, in UTC.

client.create_diagnostic(computer_id:, session:) asks Pine to investigate the Computer's recorded work. Send the ID of the diagnostic it creates.

By approval Approved developers get the integration guides, the API reference and the SDKs.