playwright "page.goto: net::ERR_CONNECTION_REFUSED" - the webServer didn't start in time in CI

Start the web server inside the Playwright config and wait for it properly. Locally you run the dev server by hand before the tests, so it is always up; in CI nothing starts it, and the first page.goto hits a port with nothing listening - hence connection refused. Put a webServer block in your Playwright config with the command that starts your app and a URL or port to wait on, and give it a generous startup timeout. Playwright will then start the server, wait until it responds, and only then run the tests. If it still fails, the server is either binding to an address the test process cannot reach or crashing on boot - check the webServer logs, not the test logs.

playwright "page.goto: net::ERR_CONNECTION_REFUSED"  -  the webServer didn't start in time in CI

Steps

1. Add a webServer block to playwright.config: the command that boots your app in CI mode, plus the URL or port Playwright should wait for. Set the startup timeout higher than your slowest cold boot (60 seconds or more is normal in CI). Expected: Playwright starts the server itself and the tests only begin after the URL responds.

2. Check the server binds to an address the tests can reach. A dev server bound to the loopback-only address is fine locally but unreachable from some CI network setups - bind to the all-interfaces address in CI. Expected: page.goto reaches the server on the first try instead of refusing the connection.

3. Read the webServer output in the CI log, not just the test error. If the server crashes on boot (missing env var, failed migration), the test error will say connection refused while the real error is three screens up in the server logs. Expected: you have seen the server's own startup logs and it reports listening successfully.

4. Make sure the port in the config matches the port the server actually uses in CI. CI env files love to override ports - a mismatch means Playwright waits on the wrong port until the timeout. Expected: config port and server port agree, verified in the logs.

5. Run the whole thing twice in CI. Server-startup races are timing dependent - one green run after a config change can be luck. Expected: two consecutive CI runs start the server and go green without retries.

Use this when

• page.goto failing with net::ERRCONNECTIONREFUSED only in CI
• tests pass locally because you start the dev server manually
• the app server needs to be booted as part of the test run

Not for this skill when

• connection refused against a staging or production URL (that is a deploy or networking issue, not a webServer config problem)
• DNS resolution failures or TLS errors (different error strings, different fixes)

Variant phrasings

playwright webServer not starting

The config-side phrasing. Same fix: webServer block, correct command, sufficient timeout.

ERRCONNECTIONREFUSED playwright CI

Shorter phrasing, same symptom. Always check server logs before test logs.

Why it happens

page.goto fails with connection refused when nothing is listening on the target port. Locally the developer starts the server first, so the port is always warm; CI runs each step in a fresh environment where the server was never started. Playwright's webServer option exists exactly for this: it boots the server as part of the test run and polls the URL until it responds. When it still fails, the causes are almost always a bind-address mismatch (server listening where tests cannot reach), a port mismatch, or the server crashing during boot - all visible in the server's own logs.

Edge cases

• the server takes longer than the default webServer timeout on first boot (cold dependency install, DB migrations): raise the timeout rather than the test timeout
• reusing an already-running server locally while CI boots fresh: set reuseExistingServer so local runs do not boot a second copy
• the app needs seed data or migrations before it serves traffic: run those as part of the webServer command chain, not as a separate CI step that races the tests

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_gKpuXwendxtH4O3Lj2vkig