---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/troubleshooting
markdown_url: https://steel.dev/docs/troubleshooting.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Troubleshooting
description: Find the error or the problem that you see, grouped by what you are doing, and go to the page that explains its cause and its fix.
summary: Find the error or the problem that you see, grouped by what you are doing, and go to the page that explains its cause and its fix.
type: troubleshooting
reviewed: 2026-11-12
prerequisites: []
related:
  - https://steel.dev/docs/faq.md
  - https://steel.dev/docs/support.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# Troubleshooting

Each entry links to the page that has the cause and the fix. An entry starts with the error code when the API returns one. Otherwise, it starts with the first words of the error message, or with what you see when there is no message. A word in capitals, such as `SESSION_ID`, stands for a value in your message.

- [A session does not start](https://steel.dev/docs/troubleshooting#a-session-does-not-start)
- [Billing, plans and limits](https://steel.dev/docs/troubleshooting#billing-plans-and-limits)
- [CDP, Playwright and Puppeteer](https://steel.dev/docs/troubleshooting#cdp-playwright-and-puppeteer)
- [A session ends early](https://steel.dev/docs/troubleshooting#a-session-ends-early)
- [Bot detection and CAPTCHAs](https://steel.dev/docs/troubleshooting#bot-detection-and-captchas)
- [Stealth Browser](https://steel.dev/docs/troubleshooting#stealth-browser)
- [Proxies and dedicated IPs](https://steel.dev/docs/troubleshooting#proxies-and-dedicated-ips)
- [Logins, profiles and credentials](https://steel.dev/docs/troubleshooting#logins-profiles-and-credentials)
- [Quick actions](https://steel.dev/docs/troubleshooting#quick-actions)
- [Commands](https://steel.dev/docs/troubleshooting#commands)
- [MCP server and CLI](https://steel.dev/docs/troubleshooting#mcp-server-and-cli)
- [Files and extensions](https://steel.dev/docs/troubleshooting#files-and-extensions)
- [Live view and recordings](https://steel.dev/docs/troubleshooting#live-view-and-recordings)
- [If nothing matches](https://steel.dev/docs/troubleshooting#if-nothing-matches)

## A session does not start

- [`invalid_api_key`](https://steel.dev/docs/account/api-keys#invalid-api-key): The Steel API key is wrong, or someone revoked it.
- [`missing_api_key`](https://steel.dev/docs/account/api-keys#missing-api-key): The request has no API key.
- [`This API key is scoped to the whole organization`](https://steel.dev/docs/account/api-keys#this-api-key-is-scoped-to-the-whole-organization): The request uses an organization key and names no project.
- [`invalid_request`](https://steel.dev/docs/reference/errors#invalid-request): A field of the request is missing or has a wrong value.
- [`No browser capacity is currently available.`](https://steel.dev/docs/reference/errors#errors-without-a-code): Steel has no browser capacity now.
- [`Steel could not start a browser session.`](https://steel.dev/docs/reference/errors#errors-without-a-code): The browser did not start, so no session runs. Steel can still list the attempt as a session with the status `failed`.
- [`The browser session did not become ready in time.`](https://steel.dev/docs/reference/errors#errors-without-a-code): The browser took too long to start.
- [`Steel hit an unexpected server error`](https://steel.dev/docs/reference/errors#errors-without-a-code): The error is on Steel's side.

## Billing, plans and limits

- [`insufficient_funds`](https://steel.dev/docs/sessions#insufficient-funds): Your account is out of credits.
- [`budget_exceeded`](https://steel.dev/docs/reference/errors#budget-exceeded): Your account reached its monthly spending limit.
- [`concurrency_limit_reached`](https://steel.dev/docs/sessions#concurrency-limit-reached): Your organization runs as many sessions as its plan allows.
- [`rate_limited`](https://steel.dev/docs/reference/errors#rate-limited): You sent requests faster than your plan allows.
- [`session_timeout_exceeded`](https://steel.dev/docs/sessions/timeouts#session-timeout-exceeded): The `timeout` is longer than your plan allows.
- [`account_suspended`](https://steel.dev/docs/reference/errors#account-suspended): Steel suspended your organization.

## CDP, Playwright and Puppeteer

- [`401 Unauthorized`](https://steel.dev/docs/control/cdp#401-unauthorized): The connection URL has no valid token, for example because it came from `sessions.list`.
- [`404 Not Found`](https://steel.dev/docs/control/cdp#404-not-found): The session ended.
- [`503 Service Unavailable`](https://steel.dev/docs/control/cdp#503-service-unavailable): The browser may still be starting.
- [The connection closes while the program runs](https://steel.dev/docs/control/cdp#the-connection-closes-while-the-program-runs): The session ended.
- [`CDP method 'METHOD' is not permitted in this environment`](https://steel.dev/docs/control/cdp#cdp-methods-that-steel-restricts): Steel blocks a few CDP methods.

## A session ends early

- [`releaseReason` is `timeout`](https://steel.dev/docs/sessions/timeouts#releasereason-is-timeout): The session reached its `timeout`.
- [`releaseReason` is `inactivity_timeout`](https://steel.dev/docs/sessions/timeouts#releasereason-is-inactivity-timeout): The session had no activity for the time in `inactivityTimeout`.
- [`releaseReason` is `browser_crashed`, `startup_failed` or `creation_timeout`](https://steel.dev/docs/observability/debug-a-failed-session#2-check-the-signals): The browser stopped, or it did not start.
- [`releaseReason` is `browser_closed`](https://steel.dev/docs/observability/debug-a-failed-session#2-check-the-signals): The browser or your agent closed the browser.
- [An API call returns `Session not found`](https://steel.dev/docs/reference/errors#errors-without-a-code): The ID is wrong, the session ended, or it is in another project.

## Bot detection and CAPTCHAs

- [The site blocks the browser or shows a challenge](https://steel.dev/docs/stealth/get-past-bot-detection#find-out-what-blocked-you): The site's bot detection reacted to the session.
- [A CAPTCHA ends in `failed_to_solve`](https://steel.dev/docs/stealth/captcha-solving#a-captcha-ends-in-failed-to-solve): The page did not accept the answer, or Steel does not solve that kind of CAPTCHA.
- [The page stays blocked after the CAPTCHA](https://steel.dev/docs/stealth/captcha-solving#the-page-stays-blocked-after-the-captcha): The site blocks the IP address or the behavior.
- [`Could not start CAPTCHA solving`](https://steel.dev/docs/stealth/captcha-solving#could-not-start-captcha-solving): Steel could not reach the session's browser. Try the call again.
- [`deposit_required`](https://steel.dev/docs/stealth/captcha-solving#deposit-required): On Launch, CAPTCHA solving needs a verified account.
- [`plan_feature_unavailable`](https://steel.dev/docs/stealth/captcha-solving#plan-feature-unavailable): The legacy Hobby plan does not include CAPTCHA solving.

## Stealth Browser

- [`The useStealthBrowser experimental feature is not enabled for this organization`](https://steel.dev/docs/stealth/stealth-browser#the-usestealthbrowser-experimental-feature-is-not-enabled): Your organization has no access to Stealth Browser, or its trial ended.
- [`core_browser_locked`](https://steel.dev/docs/stealth/stealth-browser#core-browser-locked): Your organization has early access, but its plan does not include Stealth Browser.

## Proxies and dedicated IPs

- [`deposit_required`](https://steel.dev/docs/stealth/proxies#deposit-required): On Launch, Steel proxies need a verified account.
- [`plan_feature_unavailable`](https://steel.dev/docs/stealth/proxies#plan-feature-unavailable): The legacy Hobby plan does not include Steel proxies.
- [`invalid_proxy_config`](https://steel.dev/docs/reference/errors#invalid-proxy-config): `useProxy` is not in a form that Steel accepts.
- [`invalid_proxy_url`](https://steel.dev/docs/reference/errors#invalid-proxy-url): The proxy URL is not a valid `http://` or `https://` URL.
- [`net::ERR_TUNNEL_CONNECTION_FAILED` or `net::ERR_PROXY_CONNECTION_FAILED`](https://steel.dev/docs/stealth/proxies#net-err-tunnel-connection-failed): The browser did not reach the site through the proxy.
- [A site loads without a proxy, but not through a Steel proxy](https://steel.dev/docs/stealth/proxies#a-site-loads-without-a-proxy-but-not-through-a-steel-proxy): Steel's proxy providers block some sites.
- [`No active fixed IP proxies are available for this organization`](https://steel.dev/docs/stealth/dedicated-ips#no-active-fixed-ip-proxies-are-available): Your organization has no active dedicated IP.
- [`Fixed IP proxy was not found or is not active for this organization`](https://steel.dev/docs/stealth/dedicated-ips#fixed-ip-proxy-was-not-found-or-is-not-active): The `id` in `useProxy` is not one of your active dedicated IPs.

## Logins, profiles and credentials

- [A session from a saved profile starts signed out](https://steel.dev/docs/logins/stay-signed-in#3-handle-a-login-that-expired): The site ended the login.
- [`profile_not_ready`](https://steel.dev/docs/logins/profiles#profile-not-ready): The session that saves the profile is still running, or Steel is still saving it.
- [`profile_upload_failed`](https://steel.dev/docs/logins/profiles#profile-upload-failed): Steel could not save the profile.
- [`profile_not_found`](https://steel.dev/docs/logins/profiles#profile-not-found): The ID is wrong, the profile is in another project, or Steel deleted it.
- [`Session 'SESSION_ID' is not live, so its context cannot be read`](https://steel.dev/docs/logins/session-context#session-is-not-live-so-its-context-cannot-be-read): The session ended before you exported its context.
- [`A credential already exists for origin`](https://steel.dev/docs/logins/credentials#a-credential-already-exists-for-origin): The namespace already holds a credential for that origin.
- [`No credential found for origin`](https://steel.dev/docs/logins/credentials#no-credential-found-for-origin): No credential matches that origin and namespace.
- [The sign-in form stays empty](https://steel.dev/docs/logins/credentials#the-sign-in-form-stays-empty): Steel does not find a credential for the page, or it does not fill the form.

## Quick actions

- [`'url' must point to a public destination.`](https://steel.dev/docs/control/scrape#url-must-point-to-a-public-destination): The URL names `localhost` or a private address.
- [`The hostname in 'url' could not be resolved.`](https://steel.dev/docs/control/scrape#url-must-point-to-a-public-destination): The host does not resolve to an address.
- [`The scrape action timed out while waiting for the page.`](https://steel.dev/docs/control/scrape#the-scrape-action-timed-out): The page did not load in time.
- [`deposit_required`](https://steel.dev/docs/control/scrape#deposit-required): On Launch, `useProxy` needs a verified account.
- [`Steel proxies are not available for scraping on the hobby plan.`](https://steel.dev/docs/control/scrape#steel-proxies-are-not-available-for-scraping-on-the-hobby-plan): The legacy Hobby plan does not include Steel proxies.

## Commands

- [`session_ended` or `session_not_found`](https://steel.dev/docs/reference/errors#commands-api-errors): The session ended, or its ID is wrong.
- [`delivery_failed`](https://steel.dev/docs/reference/errors#commands-api-errors): Steel could not reach the session's browser.
- [Another error code from the Commands API, such as `queue_full`](https://steel.dev/docs/reference/errors#commands-api-errors): The whole request failed.
- [`stale_ref`](https://steel.dev/docs/reference/errors#command-result-errors): The ref's element left the page, or it changed.
- [Another error code in a command's result, such as `not_actionable`](https://steel.dev/docs/reference/errors#command-result-errors): One command failed, and the commands after it did not run.

## MCP server and CLI

- [`The access token is not valid for this MCP server. Sign in again.`](https://steel.dev/docs/control/mcp-server#the-access-token-is-not-valid-for-this-mcp-server-sign-in-again): The token expired, or it is for another server.
- [`The project this sign-in was approved for no longer exists.` or `The access token names no project.`](https://steel.dev/docs/control/mcp-server#the-project-this-sign-in-was-approved-for-no-longer-exists-sign-in-again): The sign-in names no project, or its project no longer exists.
- [`Sign in to Steel, or send your Steel API key`](https://steel.dev/docs/control/mcp-server#sign-in-to-steel-or-send-your-steel-api-key): The request has no sign-in and no valid API key.
- [`Could not create a session: your plan allows`](https://steel.dev/docs/control/mcp-server#could-not-create-a-session-your-plan-allows): The agent created sessions faster than your plan allows.
- [The shell cannot find `steel` after you install it](https://steel.dev/docs/control/cli#install-the-cli): The install script does not update the `PATH` of the current shell.
- [A `steel` command exits with a code other than `0`](https://steel.dev/docs/reference/cli#exit-codes): The code names the kind of error.

## Files and extensions

- [A file that the browser downloads is not on your machine](https://steel.dev/docs/sessions/files#download-files-from-a-session): The browser saves it in the session's `/files` folder.
- [`CDP method 'DOM.setFileInputFiles' was blocked`](https://steel.dev/docs/control/cdp#cdp-methods-that-steel-restricts): The file is not in the session's files.
- [`A file path is required`](https://steel.dev/docs/sessions/files#a-file-path-is-required): The path starts with `/` or holds `..`.
- [`Session 'SESSION_ID' is 'STATUS', not running, so this file operation cannot be performed live`](https://steel.dev/docs/sessions/files#the-session-is-not-running): You uploaded or deleted a file after the session ended.
- [`Extension already exists in your organization`](https://steel.dev/docs/sessions/extensions#extension-already-exists-in-your-organization): Your organization already has this extension.
- [`Extension file must be a .zip archive or .crx file`](https://steel.dev/docs/sessions/extensions#extension-file-must-be-a-zip-archive-or-crx-file): The uploaded file has no name, or its name does not end in `.zip` or `.crx`.
- [`Extension 'EXTENSION_ID' was not found in your organization`](https://steel.dev/docs/sessions/extensions#extension-was-not-found-in-your-organization): The ID does not match an extension of your organization.

## Live view and recordings

- [The live view stays blank](https://steel.dev/docs/observability/live-view#the-live-view-stays-blank): The session ended, or the page cannot show the video.
- [The live view shows `Session not found`](https://steel.dev/docs/observability/live-view#session-not-found): The URL has no valid viewer token.
- [`This session has no recording.`](https://steel.dev/docs/observability/recordings#this-session-has-no-recording): The session ran with `recording: false`, or it was headless.
- [The video stops playing after a few hours](https://steel.dev/docs/observability/recordings#the-video-stops-playing-after-a-few-hours): The signed URLs in the playlist expired.

## If nothing matches

- [Errors](https://steel.dev/docs/reference/errors): Look up an API error by its code or its status.
- [Debug a failed session](https://steel.dev/docs/observability/debug-a-failed-session): Find the step that failed, from the session's signals, recording and logs.
- [Logs](https://steel.dev/docs/observability/logs): Read the requests, console messages and errors of the session's pages.
- [Steel status](https://status.steel.dev): See whether a Steel service is down.
- [Support](https://steel.dev/docs/support): Contact Steel with the session ID and the full error.
