Client Login

Browser Automation Troubleshooting

8 min read

Use this guide to troubleshoot Playwright, Puppeteer, and Selenium workflows that are supposed to use InstantProxies but fail, behave inconsistently, or stop working after the first successful run.

In browser automation, a visible page error does not always mean the proxy is broken. The problem may come from the access method, browser launch configuration, authentication handling, page timing, runtime environment, or the workflow built on top of the browser.

Use this page when

Use this page when:

  • the browser launches but the page does not load correctly
  • the proxy works with cURL but fails in a browser framework
  • browser automation works once and then becomes inconsistent
  • Playwright, Puppeteer, or Selenium behaves differently across environments
  • you need a practical way to isolate the failure before changing more code

If you have not yet validated the proxy outside browser automation, start with First Request with cURL and Authentication and Access.

Start with the smallest possible browser path

Do not begin with the full workflow.

Reduce the problem to:

  1. browser launch
  2. one simple page load
  3. one baseline response such as an IP check page

If the reduced browser path fails, the problem is usually earlier than the larger workflow makes it appear.

First question: does the proxy work outside the browser framework?

Before debugging Playwright, Puppeteer, or Selenium, verify that the same proxy works from the same environment with cURL.

If cURL fails too, the problem is usually:

  • wrong host or port
  • wrong authentication method
  • wrong runtime IP for allowlisting
  • a connection or access issue outside the browser framework

If cURL works but the browser fails, the next issue is more likely in browser setup or workflow behavior.

Common failure boundary 1: browser launch is not using the proxy correctly

This usually happens when:

  • the proxy is not applied at browser launch
  • the wrong proxy format is passed to the browser
  • credentials are handled incorrectly for the framework
  • the client is launching correctly but not routing traffic through the intended proxy path

Check:

  • host and port are correct
  • the proxy is configured in the browser launch settings, not later in the workflow
  • the framework-specific authentication method is correct
  • the same settings work in a minimal browser script

If the baseline setup is still unclear, continue to Endpoints, Protocols, and Connection Strings.

Common failure boundary 2: the access method does not match the runtime

A browser workflow may fail because the wrong access model is being used.

Typical cases include:

  • using IP authorization from a runtime whose public IP is not actually authorized
  • using credentials incorrectly in the browser framework
  • testing locally and assuming the same access applies on a server, container, or CI runner

Check:

  • whether the browser runtime is actually using the environment you expect
  • whether the real public IP is authorized if using IP allowlisting
  • whether credentials are being passed the way the framework expects

If access is the main issue, continue to Authentication and Allowlist Errors.

Common failure boundary 3: page load succeeds but the workflow still fails

A browser reaching a page does not prove the workflow is ready for the next step.

Common causes include:

  • weak wait strategy
  • selector timing issues
  • page state changing after navigation
  • JavaScript-heavy pages not being ready when the next action begins
  • cookies or session state carrying over in ways you did not intend

Check whether the failure happens:

  • before navigation
  • during navigation
  • after navigation but before the next intended action
  • only after repeated workflow steps

If the page loads once but the full flow still fails, the issue is usually in timing, session behavior, or step sequencing.

Common failure boundary 4: repeated runs become unstable

One successful run is not enough.

A browser workflow may work once and then fail because of:

  • state drift across runs
  • cookie or session reuse
  • context or browser reuse assumptions
  • unstable browser timing under repeated execution
  • framework-specific authentication behavior that is only partially working

Repeat the same reduced browser path several times and check:

  • whether the browser still launches cleanly
  • whether the same page still loads the same way
  • whether timing changes across runs
  • whether the runtime environment stayed the same

Repeated-run stability is more useful than first-run success.

Common failure boundary 5: the browser framework and the runtime environment do not behave the same everywhere

Browser automation often changes behavior across:

  • local development
  • servers
  • containers
  • CI runners
  • remote browser or grid environments

A setup that works locally may still fail elsewhere because:

  • the public IP is different
  • credentials are injected differently
  • the browser binary or driver behaves differently
  • the environment has different timing or resource constraints

Compare the same minimal browser path across environments before changing the workflow itself.

Common failure boundary 6: Selenium-specific authentication behavior is different from Playwright or Puppeteer

Selenium proxy authentication is often more environment-sensitive than Playwright or Puppeteer.

If Selenium is the only framework failing, check:

  • whether IP authorization is a simpler fit than credentials for that environment
  • whether browser and driver startup are both healthy
  • whether authenticated proxy behavior is being handled consistently in the real runtime

Do not assume that a credential pattern working in Playwright or Puppeteer will behave the same way in Selenium.

Common failure boundary 7: target-site behavior is being mistaken for proxy failure

Some failures are not caused by the proxy path at all.

Examples include:

  • page blocks
  • CAPTCHA challenges
  • destination-side rejection
  • unstable target-side rendering
  • pages that behave differently under automation

Check whether:

  • the proxy path itself is healthy in a simpler validation request
  • the browser reaches the destination consistently before the problem appears
  • the same target issue appears across frameworks or runtimes

If the issue appears after the browser is already navigating correctly, the destination path may be the main problem.

If this distinction is still unclear, continue to Local Failures vs Target-Site Blocks and CAPTCHAs, Bans, and Destination Limits.

Framework-specific checks

Playwright

Check:

  • the proxy is configured at browser launch
  • credentials are passed in the proxy object when required
  • browser contexts are being reused only when intended
  • the same simple page path works repeatedly

If you need framework-specific setup guidance, continue to Playwright Proxy Setup.

Puppeteer

Check:

  • the proxy is passed in Chromium launch arguments
  • page.authenticate() is used before navigation when credentials are required
  • page state and cookies are not creating hidden repeated-run problems
  • the same minimal script works several times in the same environment

If you need framework-specific setup guidance, continue to Puppeteer Proxy Setup.

Selenium

Check:

  • the proxy is configured before the WebDriver session starts
  • browser and driver compatibility are not causing a false proxy diagnosis
  • the runtime environment actually matches the allowlisted IP model if used
  • a minimal startup-and-navigation flow works consistently

If you need framework-specific setup guidance, continue to Selenium Proxy Setup.

Common mistakes

Typical issues include:

  • debugging the full browser workflow before proving the baseline browser path
  • assuming a page load means the workflow is ready for the next step
  • using the wrong runtime IP for allowlisting
  • hardcoding credentials
  • treating repeated-run instability as if it were a one-time connection problem
  • assuming target-side blocks are proxy failures without checking the boundary
  • changing multiple variables at once while the failure surface is still unclear

These patterns make browser troubleshooting slower and noisier.

Use this sequence:

  1. verify the same proxy works with cURL from the same environment
  2. reduce the browser setup to the smallest possible script
  3. confirm the browser is actually using the proxy
  4. check whether the access method matches the real runtime
  5. identify whether the failure starts at launch, navigation, or later interaction
  6. repeat the same minimal browser path several times
  7. only then expand back into the larger workflow

Key points

  • browser troubleshooting should start with the smallest working path, not the full workflow
  • cURL validation from the same environment is one of the fastest baseline checks
  • browser automation failures may come from access setup, launch configuration, timing, repeated-run drift, or target-site behavior
  • a page load does not always mean the workflow is ready for the next step
  • repeated-run consistency is a stronger signal than one successful browser run
  • framework-specific setup differences matter, especially in Selenium

Next step

If the issue appears to be access-related, continue to Authentication and Allowlist Errors.

If the browser is launching correctly but timing and navigation are still unstable, continue to Timeouts, Retries, and Backoff.