Troubleshooting Guide

Learn how to handle unexpected behaviour or low success rates when using Headless Browser.

Symptom	Likely cause	Solution
401 invalid credentials (creds are correct)	Using ws:// scheme	Switch to wss://
401 invalid credentials	Bare username without suffix	Use the full username with the suffix token from the dashboard (e.g., _ab12)
CDP_SESSION_RATE_LIMIT_REACHED	You are trying to launch too many browsers per second	Stay within the 10 sessions-per-second limit or contact support to raise the cap.
CDP_MAX_CONCURRENT_SESSIONS_REACHED	Your active session count reached the limit	Stay under 100 concurrent session total or contact support to raise the cap.
Session inspection (VNC) unable to connect (browser starts)	Max VNC limit reached	Use fewer VNC sessions.
TLS / certificate error	Certificate validation in Node.js	Set NODE_TLS_REJECT_UNAUTHORIZED="0" before requiring Playwright (testing only).
CDP_LIMIT_REACHED: profile limit reached	o_profile count exceeds max_profiles (default: 5)	Reuse one stable profile name, delete unused profiles in the Dashboard (hb.oxylabs.io/dashboard), or contact support to raise the cap.
400 session_name must be 3-36 alphanumeric or '-'	Underscore or invalid chars in session_name	Use only letters, digits, and hyphens ([A-Za-z0-9-]).
Profile restored but cookies are empty	Exit IP changed between sessions	Pin proxy_resi_ses_id + proxy_resi_ses_time with identical values every session.
Login wall / low success rate	IP reputation, wrong geolocation, or engine mismatch	Set p_cc (+ p_city), try a different p_device, or retry on a fresh session.
Target blocked entirely	Restricted target category	Complete KYC via your Dedicated Account Manager.

Still stuck? Contact Oxylabs support via live chat or email ([e-mail]).

If you're experiencing unexpected behaviour or low success rates, consider the following steps:

Understand our CAPTCHA handling process

Familiarize yourself with our CAPTCHA handling methods and its usage. This can provide insight into whether CAPTCHA challenges are the source of the issue.

Use the country parameter

Specifying a country parameter in your requests can significantly increase success rates. This ensures your requests are routed through IPs from a specific geographic location, filtering out IPs from random or potentially less reliable locations.

You can specify a country for your browser session by adding the ?p_cc parameter to your connection URL. More information can be found in section Geolocation targeting.

Use the device type parameter

Experimenting with a device parameter can result in higher success rates. You can customize how the browser emulates different device types by using the ?p_device parameter. More information can be found in Device Type section.

If issues persist after trying these steps, please contact your Dedicated Account Manager with details of the problem and the steps you've already taken.

Need a feature enabled?

Some Headless Browser features are limited by default. To adjust your limits, contact Oxylabs support (live chat or email) or your Dedicated Account Manager:

• More persistent profiles – raise your account's default cap of 5 saved profiles.
• More persistent sessions – raise your account's default cap of 5 concurrent persistent sessions.
• Restricted targets – unlock more target categories via KYC process.
• Higher rate limits – increase beyond 100 concurrent sessions / 10 per second.