Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.

When a Laravel Dusk test fails only with Chrome headless, the --headless flag is rarely the first thing to blame. Check the browser and ChromeDriver versions, driver permissions and startup, the WebDriver endpoint, the test application’s availability and APP_URL, and the viewport used by the test. Headless Chrome has no visible window and does not need a display server; adding flags such as --disable-gpu or --no-sandbox without evidence can hide the real problem rather than fix it.

Start by identifying what failed

“Headless failure” can describe several different breakpoints. A browser may never start; ChromeDriver may not accept a session; the browser may start but fail to load the Laravel application; or the page may load while a visual assertion behaves differently from a headed run. Those symptoms point to different checks. Diagnose the first failing boundary rather than changing Chrome flags all at once.

  • Driver or session startup fails: check Chrome/ChromeDriver compatibility, executable permissions, whether the driver started, and whether Dusk can reach its WebDriver endpoint.
  • The browser starts but the app does not load: check that the application server is running and that APP_URL resolves to that server.
  • The app loads but a layout or screenshot assertion differs: compare viewport size and run headed and headless with otherwise equivalent settings.
  • The failure is intermittent in CI: check process startup order and readiness before treating it as a rendering issue.

This order matters: a refused connection to ChromeDriver is not evidence that a page rendered incorrectly, and a page-load failure is not necessarily evidence that Chrome itself is broken.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Check Chrome and ChromeDriver compatibility first

Laravel Dusk uses Google Chrome with a standalone ChromeDriver by default. The installed driver needs to be compatible with the installed Chrome or Chromium browser. A mismatch can prevent a WebDriver session from being created, which may look like a headless-mode failure even though the browser has not reached the point of rendering your page.

#1 Best Overall
  1. From the Laravel project directory, run php artisan dusk:chrome-driver --detect.
  2. Confirm that the detected or installed ChromeDriver is compatible with the Chrome or Chromium version available in the environment running the tests.
  3. Repeat the check in CI, not only on a developer workstation. The browser installed on the CI host may differ from the local browser.

If the test passes locally but fails in CI, compare the actual browser and driver versions in both places. Do not assume that a working local Dusk installation proves the CI installation has a matching pair.

Verify the driver can execute and accept connections

Check executable permissions

Dusk needs executable ChromeDriver binaries. Laravel documents this permissions command:

chmod -R 0755 vendor/laravel/dusk/bin/

Use it where the test environment has lost the executable bit—for example, after a checkout or dependency installation that leaves the driver binary non-executable. Then retry Dusk and inspect the first driver-startup error. Changing permissions will not repair a version mismatch or an application URL that points to the wrong place.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Interpret a refused connection to port 9515

A connection refused at localhost:9515 means the WebDriver endpoint was not reachable when Dusk tried to create the browser session. The useful questions are whether ChromeDriver started, whether it could execute, whether it is listening on the expected port, and whether its version is compatible with the browser. The message alone does not establish which of those is wrong.

Rank #2
Dell Latitude 3190 11.6" HD 2-in-1 Touchscreen Laptop Intel N5030 1.1Ghz 4GB Ram 128GB SSD Windows 11 Professional (Renewed)
  • 1.1 GHz (boost up to 2.4GHz) Intel Celeron N5030 Quad-Core
  • 4GB DDR4 System Memory; 128GB Solid State Drive
  • 11.6" HD (1366 x 768) Multi-Touch Display
  • Combo headphone/microphone jack - Noble Wedge Lock slot - HDMI; 2 USB 3.1 Gen 1
  • Windows 11 Pro
  • Check the driver binary’s permissions and compatibility.
  • Check whether another process or a failed prior run has affected the expected port.
  • Confirm that ChromeDriver is actually listening when Dusk attempts to connect.
  • Check whether the driver and Dusk are configured to use the same endpoint.

Dusk normally uses port 9515. If you choose to start ChromeDriver manually, comment out static::startChromeDriver() so Dusk does not also try to start its own driver, and configure the matching RemoteWebDriver URL for the manually started process. Avoid running both startup paths at once: duplicate or mismatched driver management makes connection errors harder to diagnose.

Make sure the Laravel application is reachable

A running browser and driver do not guarantee that the test application is available. In CI, start the application server before running php artisan dusk, and set APP_URL to the address served by that process. A commonly used CI address is http://127.0.0.1:8000, but it is correct only if the server is actually listening there.

  1. Start the Laravel application server as a background process in the test job.
  2. Set APP_URL to the server’s reachable address, such as http://127.0.0.1:8000 when that is where the job serves the app.
  3. Start ChromeDriver if your setup manages it manually; otherwise let Dusk start it through its normal path.
  4. Wait until the required processes are ready, then run php artisan dusk.

The key is ordering and reachability, not merely issuing all the commands in one job. If Dusk starts while the server or driver is still coming up, the test can fail before either service is ready. A correct APP_URL also needs to resolve from the process running Chrome; a URL that works in a developer’s browser is not proof that it is reachable in the CI environment.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Separate headless behavior from viewport and timing differences

Headless Chrome has no visible browser window. Chrome’s documentation says a display server such as Xvfb is no longer needed for headless Chrome. Therefore, installing a virtual display should not be the default response to a headless-only failure.

Rank #3
Dell Latitude 5420 14" FHD Business Laptop Computer, Intel Quad-Core i5-1145G7, 16GB DDR4 RAM, 256GB SSD, Camera, HDMI, Windows 11 Pro (Renewed)
  • 256 GB SSD of storage.
  • Multitasking is easy with 16GB of RAM
  • Equipped with a blazing fast Core i5 2.00 GHz processor.

For responsive-layout or screenshot-sensitive assertions, set a fixed window size. A test that depends on the available viewport can encounter a different layout when the browser’s dimensions differ between local and CI runs. When investigating, compare headed and headless executions using the same browser and driver versions, application URL, viewport, and process setup. Change one condition at a time so the comparison can reveal which difference matters.

Also distinguish a timing problem from a layout problem. If the application or driver is not ready when the test begins, changing viewport dimensions will not fix it. First establish that the same page loads reliably in both modes; then investigate visual differences at a deterministic size.

Do not add Chrome flags as a universal remedy

--disable-gpu is documented by Chrome as a temporary workaround for particular bugs, not a general requirement for headless runs. Add or remove it only as a targeted experiment tied to a reproducible Chrome issue. Record the browser version and the exact behavior that changes, then remove the flag if it does not address that behavior.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

The same diagnostic caution applies to --no-sandbox: the available evidence does not establish it as a universal fix for Dusk headless failures. Do not treat either flag as a substitute for compatible binaries, valid permissions, a reachable driver, or a live test application. Broad flag changes can make a CI job behave differently without showing which underlying failure was corrected.

Rank #4
15.6 Inch Laptop Computer, N4020, 4GB DDR4 RAM, 128GB eMMC,with Windows 11
  • EFFORTLESS EVERYDAY PERFORMANCE: Powered by Intel Celeron N4020 processor and Windows 11 Home system, delivering reliable, low-power efficiency for daily tasks like document editing, email, online classes, and web browsing
  • 15.6-INCH FULL HD DISPLAY: Enjoy immersive visuals on the 15.6" FHD (1920x1080) anti-glare screen with micro-edge bezels. Delivers clear details and comfortable viewing for long study sessions, working on spreadsheets, and video playback
  • RESPONSIVE MULTITASKING & STORAGE: Built with 4GB LPDDR4 RAM and 128GB eMMC storage for smooth daily essential use. Expand your storage by up to 1TB via the integrated TF card slot to easily store movies, photos, and working files
  • ADVANCED CONNECTIVITY: Outfitted with 2x Full-Featured Type-C ports for data transfer, fast charging, and dual-monitor output, alongside 2x USB 3.2 Gen1 ports and a 3.5mm audio jack for complete peripheral compatibility
  • LIGHTWEIGHT & SILENT OPERATION: Slim and portable for effortless travel or commuting. Features a 1MP HD webcam for remote meetings, 38Wh battery with 45W Type-C fast charging, and a fanless silent design for peaceful work environments.

Use a controlled comparison when local passes and CI fails

Compare the environments along these axes before changing the test itself:

What differs What to establish Why it matters
Headed versus headless Whether the same test, app URL, browser/driver pair, and viewport fail only in headless mode Separates a mode-specific rendering or timing difference from setup failures shared by both modes.
Local host versus CI host Installed browser and driver, permissions, available ports, and startup sequence CI may not have the same browser, executable bits, or process readiness as a workstation.
Chrome versus ChromeDriver The installed versions and whether the driver is compatible with the browser An incompatible pair can fail before a browser session exists.
Automatic versus manual driver startup Whether Dusk or the job starts the driver, and whether both use the same endpoint Conflicting startup paths can leave Dusk connecting to an unavailable endpoint.
Viewport The explicit window size used for each run Responsive and screenshot-sensitive assertions can depend on browser dimensions.
Application URL and timing Whether the server is live at APP_URL before Dusk starts A valid URL is insufficient if the server is not yet accepting requests.

Keep a short record of the conditions for each run: browser and driver versions, mode, viewport, driver startup method, application URL, and which process was not reachable if startup failed. This makes a “works locally” comparison actionable rather than a guess about headless Chrome.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Troubleshoot by symptom

Dusk cannot create a Chrome session

Run php artisan dusk:chrome-driver --detect, check browser/driver compatibility, and confirm that the driver binary is executable. If the message is a refusal at localhost:9515, verify the endpoint is listening at session-creation time and that the active startup method and configured URL agree.

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

CI reports a refused connection

Inspect the job’s process order. Start the server and driver before php artisan dusk and wait until they are ready. Check that the expected port is reachable and that Dusk has not been configured to connect to a different manually managed endpoint.

Best Value
Sale
15.6 Inch Win 11 Laptop Computer, N4020, 4GB DDR4 RAM, 128GB Storage
  • WINDOWS 11 | STABLE PERFORMANCE: Powered by Intel Celeron N4020 processor and Windows 11 system, this laptop delivers stable performance for everyday computing tasks. It supports web browsing, online learning, document editing, email communication, and basic office work with optimized power efficiency, providing a practical and reliable experience for essential daily use for daily use.
  • 15.6” FHD IPS DISPLAY: Features a 15.6-inch Full HD IPS display with narrow bezels, offering wider viewing angles and clearer image details compared to standard panels. The improved screen-to-body ratio enhances visual experience for study, reading, document work, and video playback, making it suitable for both productivity and entertainment use.
  • 4GB DDR4 + 128GB eMMC STORAGE: Equipped with 4GB DDR4 memory and 128GB eMMC storage for everyday basics such as browsing, documents, email, and online learning platforms. The built-in TF card slot supports storage expansion up to 1TB, giving you more flexibility for files, photos, videos, and daily documents. TF card not included.
  • CONNECTIVITY & PORTS: Includes 1× TF card slot, 2× USB 3.2 Gen1 ports, and 2× full-featured Type-C ports (USB 3.2 Gen1). The Type-C ports support data transfer, charging, and video output, enabling flexible connection with external devices such as monitors, storage, and peripherals for daily work and study use.
  • LIGHTWEIGHT DESIGN | ONLINE COMMUNICATION: Designed with a slim, portable profile, this laptop is easy to carry for school, commuting, and travel. A built-in 1MP front camera supports online classes, video meetings, remote communication, and everyday conferencing. The 3300mAh battery works with the low-power system design to support practical daily use, while thermal optimization helps maintain quieter operation during extended tasks.

The browser opens but cannot reach the application

Check that the application process is running and that APP_URL names the address it serves. In CI, http://127.0.0.1:8000 is a common value only when the server is bound and serving there.

Only visual assertions fail

Set a fixed window size and compare headed and headless results with the same viewport and browser/driver versions. This helps distinguish a responsive-layout difference from a failed browser startup or a page that never loaded.

Adding --disable-gpu appears to help

Treat that as a lead to reproduce and tie to a particular Chrome bug, not as proof that headless mode universally needs the flag. Retest with the flag changed in isolation and retain it only if it reliably addresses the identified issue.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Or skip the browser setup

If you need a clean page image as a visual reference or for a separate screenshot workflow, ScreenshotNeo can capture a URL without setting up your own screenshot browser. It is not a replacement for Laravel Dusk: it does not run your Dusk assertions or validate application interactions. For a URL screenshot, one GET request is enough; see the ScreenshotNeo documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

ScreenshotNeo accepts consent banners like a visitor and removes 60+ known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.

Sign up for 1,000 free screenshots a month, with no card required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Quick Recap

Bestseller No. 1
HP 14' HD Laptop, Windows 11, Intel Celeron Dual-Core Processor Up to 2.60GHz, 4GB RAM, 64GB SSD, Webcam, Dale Pink (Renewed)
HP 14" HD Laptop, Windows 11, Intel Celeron Dual-Core Processor Up to 2.60GHz, 4GB RAM, 64GB SSD, Webcam, Dale Pink (Renewed)
14" diagonal, 1366x768 resolution, HD BrightView LED, Glossy NON-TOUCH Display
$247.99
Bestseller No. 2
Dell Latitude 3190 11.6' HD 2-in-1 Touchscreen Laptop Intel N5030 1.1Ghz 4GB Ram 128GB SSD Windows 11 Professional (Renewed)
Dell Latitude 3190 11.6" HD 2-in-1 Touchscreen Laptop Intel N5030 1.1Ghz 4GB Ram 128GB SSD Windows 11 Professional (Renewed)
1.1 GHz (boost up to 2.4GHz) Intel Celeron N5030 Quad-Core; 4GB DDR4 System Memory; 128GB Solid State Drive
Bestseller No. 3
Dell Latitude 5420 14' FHD Business Laptop Computer, Intel Quad-Core i5-1145G7, 16GB DDR4 RAM, 256GB SSD, Camera, HDMI, Windows 11 Pro (Renewed)
Dell Latitude 5420 14" FHD Business Laptop Computer, Intel Quad-Core i5-1145G7, 16GB DDR4 RAM, 256GB SSD, Camera, HDMI, Windows 11 Pro (Renewed)
256 GB SSD of storage.; Multitasking is easy with 16GB of RAM; Equipped with a blazing fast Core i5 2.00 GHz processor.
$289.99

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.