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
- Billing, plans and limits
- CDP, Playwright and Puppeteer
- A session ends early
- Bot detection and CAPTCHAs
- Stealth Browser
- Proxies and dedicated IPs
- Logins, profiles and credentials
- Quick actions
- Commands
- MCP server and CLI
- Files and extensions
- Live view and recordings
- If nothing matches
A session does not start
invalid_api_keyThe Steel API key is wrong, or someone revoked it.missing_api_keyThe request has no API key.This API key is scoped to the whole organizationThe request uses an organization key and names no project.invalid_requestA field of the request is missing or has a wrong value.No browser capacity is currently available.Steel has no browser capacity now.Steel could not start a browser session.The browser did not start, so no session runs. Steel can still list the attempt as a session with the statusfailed.The browser session did not become ready in time.The browser took too long to start.Steel hit an unexpected server errorThe error is on Steel's side.
Billing, plans and limits
insufficient_fundsYour account is out of credits.budget_exceededYour account reached its monthly spending limit.concurrency_limit_reachedYour organization runs as many sessions as its plan allows.rate_limitedYou sent requests faster than your plan allows.session_timeout_exceededThetimeoutis longer than your plan allows.account_suspendedSteel suspended your organization.
CDP, Playwright and Puppeteer
401 UnauthorizedThe connection URL has no valid token, for example because it came fromsessions.list.404 Not FoundThe session ended.503 Service UnavailableThe browser may still be starting.- The connection closes while the program runsThe session ended.
CDP method 'METHOD' is not permitted in this environmentSteel blocks a few CDP methods.
A session ends early
releaseReasonistimeoutThe session reached itstimeout.releaseReasonisinactivity_timeoutThe session had no activity for the time ininactivityTimeout.releaseReasonisbrowser_crashed,startup_failedorcreation_timeoutThe browser stopped, or it did not start.releaseReasonisbrowser_closedThe browser or your agent closed the browser.- An API call returns
Session not foundThe ID is wrong, the session ended, or it is in another project.
Bot detection and CAPTCHAs
- The site blocks the browser or shows a challengeThe site's bot detection reacted to the session.
- A CAPTCHA ends in
failed_to_solveThe page did not accept the answer, or Steel does not solve that kind of CAPTCHA. - The page stays blocked after the CAPTCHAThe site blocks the IP address or the behavior.
Could not start CAPTCHA solvingSteel could not reach the session's browser. Try the call again.deposit_requiredOn Launch, CAPTCHA solving needs a verified account.plan_feature_unavailableThe legacy Hobby plan does not include CAPTCHA solving.
Stealth Browser
The useStealthBrowser experimental feature is not enabled for this organizationYour organization has no access to Stealth Browser, or its trial ended.core_browser_lockedYour organization has early access, but its plan does not include Stealth Browser.
Proxies and dedicated IPs
deposit_requiredOn Launch, Steel proxies need a verified account.plan_feature_unavailableThe legacy Hobby plan does not include Steel proxies.invalid_proxy_configuseProxyis not in a form that Steel accepts.invalid_proxy_urlThe proxy URL is not a validhttp://orhttps://URL.net::ERR_TUNNEL_CONNECTION_FAILEDornet::ERR_PROXY_CONNECTION_FAILEDThe browser did not reach the site through the proxy.- A site loads without a proxy, but not through a Steel proxySteel's proxy providers block some sites.
No active fixed IP proxies are available for this organizationYour organization has no active dedicated IP.Fixed IP proxy was not found or is not active for this organizationTheidinuseProxyis not one of your active dedicated IPs.
Logins, profiles and credentials
- A session from a saved profile starts signed outThe site ended the login.
profile_not_readyThe session that saves the profile is still running, or Steel is still saving it.profile_upload_failedSteel could not save the profile.profile_not_foundThe ID is wrong, the profile is in another project, or Steel deleted it.Session 'SESSION_ID' is not live, so its context cannot be readThe session ended before you exported its context.A credential already exists for originThe namespace already holds a credential for that origin.No credential found for originNo credential matches that origin and namespace.- The sign-in form stays emptySteel does not find a credential for the page, or it does not fill the form.
Quick actions
'url' must point to a public destination.The URL nameslocalhostor a private address.The hostname in 'url' could not be resolved.The host does not resolve to an address.The scrape action timed out while waiting for the page.The page did not load in time.deposit_requiredOn Launch,useProxyneeds a verified account.Steel proxies are not available for scraping on the hobby plan.The legacy Hobby plan does not include Steel proxies.
Commands
session_endedorsession_not_foundThe session ended, or its ID is wrong.delivery_failedSteel could not reach the session's browser.- Another error code from the Commands API, such as
queue_fullThe whole request failed. stale_refThe ref's element left the page, or it changed.- Another error code in a command's result, such as
not_actionableOne 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.The token expired, or it is for another server.The project this sign-in was approved for no longer exists.orThe access token names no project.The sign-in names no project, or its project no longer exists.Sign in to Steel, or send your Steel API keyThe request has no sign-in and no valid API key.Could not create a session: your plan allowsThe agent created sessions faster than your plan allows.- The shell cannot find
steelafter you install itThe install script does not update thePATHof the current shell. - A
steelcommand exits with a code other than0The code names the kind of error.
Files and extensions
- A file that the browser downloads is not on your machineThe browser saves it in the session's
/filesfolder. CDP method 'DOM.setFileInputFiles' was blockedThe file is not in the session's files.A file path is requiredThe path starts with/or holds...Session 'SESSION_ID' is 'STATUS', not running, so this file operation cannot be performed liveYou uploaded or deleted a file after the session ended.Extension already exists in your organizationYour organization already has this extension.Extension file must be a .zip archive or .crx fileThe uploaded file has no name, or its name does not end in.zipor.crx.Extension 'EXTENSION_ID' was not found in your organizationThe ID does not match an extension of your organization.
Live view and recordings
- The live view stays blankThe session ended, or the page cannot show the video.
- The live view shows
Session not foundThe URL has no valid viewer token. This session has no recording.The session ran withrecording: false, or it was headless.- The video stops playing after a few hoursThe signed URLs in the playlist expired.
If nothing matches
- ErrorsLook up an API error by its code or its status.
- Debug a failed sessionFind the step that failed, from the session's signals, recording and logs.
- LogsRead the requests, console messages and errors of the session's pages.
- Steel statusSee whether a Steel service is down.
- SupportContact Steel with the session ID and the full error.