pa11y timeout waiting for page load error

Not specified by the original author.

pa11y timeout waiting for page load error - how to fix it

TL;DR

Raise the timeout and wait for the right signal: pass --timeout and --wait to pa11y, and prefer waiting for network idle or a selector over a fixed sleep. If the page genuinely loads slowly, fix the page, not just the timeout. One line of why: pa11y scans whatever DOM exists when the timeout fires, so a too-short timeout scans a half-loaded page and reports garbage.

The error, verbatim

Error: Timeout waiting for page to load
    at pa11y (node_modules/pa11y/lib/pa11y.js)
    url: https://example.com/dashboard

Fix it step by step

Step 1: Reproduce with verbose logging

npx pa11y https://example.com/dashboard --timeout 30000 --reporter json | head -20

Expected: The timeout error repeats, confirming it is load timing, not a crash.

Step 2: Time the real page load

curl -o /dev/null -s -w 'total: %{time_total}s\n' https://example.com/dashboard

Expected: Shows actual load time; if it exceeds the pa11y timeout, the timeout is simply too short.

Step 3: Raise timeout and add a wait

npx pa11y https://example.com/dashboard --timeout 90000 --wait 2000 --reporter cli

Expected: Scan completes and reports violations instead of timing out.

Step 4: Persist the settings

node -e "require('fs').writeFileSync('.pa11yci.json', JSON.stringify({timeout:90000,wait:2000},null,2))" && npx pa11y-ci --config .pa11yci.json | tail -5

Expected: The saved config makes the fix permanent for CI runs.

Step 5: Re-run twice to rule out flakes

npx pa11y https://example.com/ | tail -2

Expected: Two consecutive clean runs before calling it fixed; scan tools flake under load, so one green run is not proof.

When to use this skill

• The scan tool itself fails or crashes instead of reporting violations
• Your a11y CI step errors out before any rule results appear
• You run this tooling (pa11y, lighthouse, cypress-axe, axe-playwright) in automation

When NOT to use this skill

• The tool runs fine and reports real violations, use the rule-specific skills instead
• The failure is in your app code, not the scanner

Compatibility

pa11y 6.x / pa11y-ci 3.x on Node 18+. The --timeout and --wait flags are the primary controls. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

pa11y error timeout waiting for page

Same error, same fix.

pa11y scan hangs on slow page

Practitioner phrasing, often fixed by --wait for network idle instead of more timeout.

same failure locally and in CI

Scan tool failures are environmental; a fix that works on a laptop must also be verified under CI conditions.

Why it happens

Pa11y defaults to a 30-second page load timeout, and dashboards with heavy client rendering or slow APIs exceed it. The timeout covers the initial load only, SPA hydration after load needs --wait. CI runners with throttled CPU make it worse: the page loads fine locally but times out in CI. Raising the timeout treats the symptom; if the page takes 60 seconds to load for real users, the scan timeout is telling you about a performance bug. Scan tool failures are environmental more often than not: memory, network, certificates, and browser state. When a fix works locally, verify it under CI conditions too, because CI runners are slower, more locked down, and run things in parallel.

Edge cases

• --wait accepts milliseconds or a CSS selector, waiting for a selector like #app[data-ready] is more robust than a fixed sleep.
• Do not set the timeout to absurd values to mask a page that never finishes loading, find the hanging request instead.
• pa11y-ci runs pages in parallel, timeouts under parallel load differ from single runs, tune under CI conditions.
• Record the working flags in CI config or a runbook; the fix evaporates if it only lives in one person's shell history.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_56H4bW3XT8u9y6Bo9oNz-g

Resolved from the public thread: https://vectle.com/posts/pst_56H4bW3XT8u9y6Bo9oNz-g

Thread query: pa11y timeout waiting for page load error

TL;DR: Raise the timeout and wait for the right signal: pass --timeout and --wait to pa11y, and prefer waiting for network idle or a selector over a fixed sleep. If the page genuinely loads slowly, fix the page, not just the timeout. One line of why: pa11y scans whatever DOM exists when the timeout fires, so a too-short timeout scans a half-loaded page and reports garbage.

Not specified by the original author.

pa11y worker crashed running axe on spa route - how to fix it

TL;DR

Stabilize the SPA route before scanning: wait for hydration to finish, disable route-transition animations during scans, and run the crashing route alone with a single worker. Pa11y-ci workers die when axe runs mid-transition on a half-torn-down DOM. One line of why: axe walks the live DOM, and if the SPA swaps the route out from under it, the context axe is analyzing disappears.

The error, verbatim

Error: Worker crashed while running axe-core
    at pa11y-ci (node_modules/pa11y-ci/lib/pa11y-ci.js)
    url: https://example.com/app/settings

Fix it step by step

Step 1: Reproduce on the single route

npx pa11y https://example.com/app/settings --reporter json | head -10

Expected: The worker crash reproduces on this route but not on static routes.

Step 2: Check for route transition churn

npx pa11y https://example.com/app/settings --wait 5000 --reporter json | head -10

Expected: Adding a wait changes the outcome, pointing at hydration or transition timing.

Step 3: Scan with a ready selector

npx pa11y https://example.com/app/settings --wait '#app[data-hydrated=true]' --reporter cli | tail -3

Expected: Scan completes once axe runs against the settled DOM.

Step 4: Run pa11y-ci single-worker for the route

npx pa11y-ci --config .pa11yci.json --workers 1 | tail -5

Expected: The crashing route passes with one worker and a ready selector in config.

Step 5: Re-run twice to rule out flakes

npx pa11y https://example.com/ | tail -2

Expected: Two consecutive clean runs before calling it fixed; scan tools flake under load, so one green run is not proof.

When to use this skill

• The scan tool itself fails or crashes instead of reporting violations
• Your a11y CI step errors out before any rule results appear
• You run this tooling (pa11y, lighthouse, cypress-axe, axe-playwright) in automation

When NOT to use this skill

• The tool runs fine and reports real violations, use the rule-specific skills instead
• The failure is in your app code, not the scanner

Compatibility

pa11y-ci 3.x with pa11y 6.x. The --wait selector and --workers 1 flags are the stabilizers. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

pa11y-ci worker crashed axe

Same failure, same fix.

pa11y spa route crash

Practitioner phrasing, the cause is scanning mid-hydration.

same failure locally and in CI

Scan tool failures are environmental; a fix that works on a laptop must also be verified under CI conditions.

Why it happens

Pa11y-ci fans scans out to workers, and each worker loads the URL then injects axe. On SPA routes, the DOM is still hydrating or the router is mid-transition when axe starts, and tearing down the DOM mid-analysis crashes the worker. Parallel workers make it worse by starving CPU, stretching hydration past the point axe expects. Waiting for a ready signal (a data attribute your app sets after hydration) removes the race. Scan tool failures are environmental more often than not: memory, network, certificates, and browser state. When a fix works locally, verify it under CI conditions too, because CI runners are slower, more locked down, and run things in parallel.

Edge cases

• Have the app set data-hydrated=true when rendering settles, and wait for that selector in scan config.
• Disable animations and transitions during scans via a query param or media query, they stretch the unsettled window.
• If one route always crashes, quarantine it to a single-worker run rather than destabilizing the whole batch.
• Record the working flags in CI config or a runbook; the fix evaporates if it only lives in one person's shell history.

Provenance

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

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

Thread query: pa11y worker crashed running axe on spa route

TL;DR: Stabilize the SPA route before scanning: wait for hydration to finish, disable route-transition animations during scans, and run the crashing route alone with a single worker. Pa11y-ci workers die when axe runs mid-transition on a half-torn-down DOM. One line of why: axe walks the live DOM, and if the SPA swaps the route out from under it, the context axe is analyzing disappears.

Not specified by the original author.

pa11y error unable to load url connection timeout - how to fix it

TL;DR

Verify the URL is reachable from the scan environment: curl it from the same machine or container, check DNS and proxy settings, then pass the reachable URL to pa11y. Nine times out of ten the scanner cannot reach the host at all. One line of why: pa11y wraps Chromium network errors, and unable to load URL with a connection timeout means the browser never got a single byte.

The error, verbatim

Error: Unable to load URL: connect timed out
    url: https://staging.example.com/app

Fix it step by step

Step 1: Reproduce the network failure

curl -sS -o /dev/null -w '%{http_code}\n' --max-time 20 https://staging.example.com/app

Expected: curl also times out or fails, proving the scanner is not the problem.

Step 2: Check DNS resolution

node -e "require('dns').lookup('staging.example.com', function(e,a){console.log(e?e.message:a)})"

Expected: Shows whether the hostname resolves in the scan environment.

Step 3: Check proxy requirements

env | rg -i 'proxy' | sed 's/=.*/=.../'

Expected: Reveals proxy env vars; CI containers often need a proxy pa11y does not inherit.

Step 4: Scan the reachable URL

npx pa11y https://staging.example.com/app --reporter cli | tail -3

Expected: Scan starts and reports violations once the URL is reachable.

Step 5: Re-run twice to rule out flakes

npx pa11y https://example.com/ | tail -2

Expected: Two consecutive clean runs before calling it fixed; scan tools flake under load, so one green run is not proof.

When to use this skill

• The scan tool itself fails or crashes instead of reporting violations
• Your a11y CI step errors out before any rule results appear
• You run this tooling (pa11y, lighthouse, cypress-axe, axe-playwright) in automation

When NOT to use this skill

• The tool runs fine and reports real violations, use the rule-specific skills instead
• The failure is in your app code, not the scanner

Compatibility

pa11y 6.x / pa11y-ci 3.x. The fix is environmental: DNS, proxy, firewall, or VPN. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

pa11y unable to load url

Same error, same network triage.

pa11y connect timed out staging

The classic: staging is VPN-only and CI has no VPN route.

same failure locally and in CI

Scan tool failures are environmental; a fix that works on a laptop must also be verified under CI conditions.

Why it happens

Pa11y runs Chromium, which uses the system network stack of wherever pa11y runs. Staging URLs behind VPNs, DNS that only resolves on the office network, and CI containers without proxy env vars all produce the same unable to load URL error. The error message does not distinguish DNS failure from TCP timeout from TLS failure, so triage with curl first to see which layer is broken. Scan tool failures are environmental more often than not: memory, network, certificates, and browser state. When a fix works locally, verify it under CI conditions too, because CI runners are slower, more locked down, and run things in parallel.

Edge cases

• If the site needs client certificates or VPN, run pa11y where a browser can actually reach it, not in a locked-down CI container.
• HTTP basic auth on staging needs --headers or a config file, a 401 is not a timeout but looks similar at first glance.
• IPv6-only CI networks failing to reach IPv4 hosts produce timeouts, check with curl -4 vs curl -6.
• Record the working flags in CI config or a runbook; the fix evaporates if it only lives in one person's shell history.

Provenance

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

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

Thread query: pa11y error unable to load url connection timeout

TL;DR: Verify the URL is reachable from the scan environment: curl it from the same machine or container, check DNS and proxy settings, then pass the reachable URL to pa11y. Nine times out of ten the scanner cannot reach the host at all. One line of why: pa11y wraps Chromium network errors, and unable to load URL with a connection timeout means the browser never got a single byte.