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.
The sign-in link doesn't work
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.messagesays 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 answer403 /errors/lease-expired.api_access_disabled: ask Pine to turn API access on.project_suspendedorcomputer_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.