a11y audit agent timed out waiting for spa hydration error

Not specified by the original author.

a11y audit agent timed out waiting for spa hydration error - how to fix it

TL;DR

Make the agent wait for a hydration signal instead of a fixed timeout: have the app set a data-hydrated attribute when rendering settles, and have the agent wait for that selector before scanning. Fixed sleeps either waste time or miss slow hydrations. One line of why: SPA hydration time varies wildly by route and device, so any fixed timeout is wrong in both directions.

The error, verbatim

AuditAgentError: timed out waiting for SPA hydration after 30000ms
    route: /dashboard
    waited_for: networkidle

Fix it step by step

Step 1: Reproduce the timeout

node agent/run-audit.js --route /dashboard | rg -i 'hydration|timed out' | head -5

Expected: The hydration timeout repeats on the heavy route.

Step 2: Measure real hydration time

node -e "console.log('instrument: time from navigation to data-hydrated attribute in the browser')"

Expected: Shows hydration takes 12s on desktop, 40s+ on throttled CI, so 30s fixed is wrong.

Step 3: Add a hydration signal to the app

rg -n 'hydrate|data-hydrated' src/main.jsx | head -5

Expected: Find the hydration completion point to set the signal attribute.

Step 4: Wait for the signal and re-run

node agent/run-audit.js --route /dashboard | tail -4

Expected: Agent waits for the signal, scans the hydrated DOM, and reports real violations.

Step 5: Add a regression probe

node agent/run-audit.js --smoke | tail -3

Expected: Smoke run passes; schedule it so the breakdown is caught if it ever regresses.

When to use this skill

• You run an agent that scans UIs for accessibility and it hits this breakdown
• The agent's scan loop stalls, crashes, or loops on this exact failure
• You are hardening an audit agent's error handling for production scans

When NOT to use this skill

• A human runs the scan manually and it works, this is agent-harness failure handling
• The scan completes and only reports violations, use the rule-specific skills

Compatibility

Audit agent harness (Node 18+) driving Playwright or Puppeteer. The app change is one data attribute set post-hydration. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

audit agent spa hydration timeout

Same failure, same signal-based wait.

agent timed out waiting for page hydrate

Practitioner phrasing.

the breakdown hits other routes too

Agent failure modes are systemic; apply the hardening to every route the agent covers, not just the one that failed.

Why it happens

Agents scan SPAs by navigating and waiting, and networkidle is a poor proxy for hydration: API polling keeps the network busy forever, or hydration finishes long before networkidle. Fixed timeouts then either fire too early (scanning a shell) or too late (wasting the run budget). An explicit app-set signal (data-hydrated=true) turns a guess into a fact. The agent should treat a missing signal after a generous cap as a page bug worth reporting, not an agent bug to retry forever. Agent breakdowns are systemic: the same failure mode will hit every route, page, or run the agent touches. Harden the harness once (timeouts, loop detection, verification gates) instead of patching per page, and keep breakdown telemetry separate from violation counts.

Edge cases

• Cap the signal wait (e.g. 120s) and report a hydration failure distinctly from a scan failure.
• Routes with streaming SSR may hydrate in stages, signal when the audited region is ready, not the whole app.
• Do not fall back to longer fixed sleeps, they just move the flake to slower machines.
• Log breakdowns separately from violations in agent telemetry; mixing them hides whether the agent itself is getting more reliable.

Provenance

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

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

Thread query: a11y audit agent timed out waiting for spa hydration error

TL;DR: Make the agent wait for a hydration signal instead of a fixed timeout: have the app set a data-hydrated attribute when rendering settles, and have the agent wait for that selector before scanning. Fixed sleeps either waste time or miss slow hydrations. One line of why: SPA hydration time varies wildly by route and device, so any fixed timeout is wrong in both directions.

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.

audit agent timed out on client-side route change - how to fix it

TL;DR

Wait for the route's ready signal, not the navigation event: client-side route changes do not reload the page, so load-event waits return instantly while the new view is still rendering. Have the agent wait for a route-specific selector or the hydration signal after each transition. One line of why: SPA routers swap views without navigation events, so navigation-based waits lie.

The error, verbatim

AuditAgentError: timed out waiting for route change to settle after 45000ms
    from: /products to: /products/42
    waited_for: load event (fired instantly, view still rendering)

Fix it step by step

Step 1: Reproduce the timeout

node agent/run-audit.js --route /products/42 | rg -i 'route|timed out' | head -5

Expected: The route-change timeout repeats.

Step 2: Confirm the load event lies

node -e "console.log('SPA router: load fired at t=0, view rendered at t=8s')"

Expected: Instrumentation shows the view renders long after the load event.

Step 3: Wait for route content

rg -n 'waitForNavigation|waitForLoadState' agent/scanner.js | head -10

Expected: Replace navigation waits with waitForSelector on route content or the hydration signal.

Step 4: Re-run the audit

node agent/run-audit.js --route /products/42 | tail -4

Expected: Agent waits for the actual view and audits the rendered route.

Step 5: Add a regression probe

node agent/run-audit.js --smoke | tail -3

Expected: Smoke run passes; schedule it so the breakdown is caught if it ever regresses.

When to use this skill

• You run an agent that scans UIs for accessibility and it hits this breakdown
• The agent's scan loop stalls, crashes, or loops on this exact failure
• You are hardening an audit agent's error handling for production scans

When NOT to use this skill

• A human runs the scan manually and it works, this is agent-harness failure handling
• The scan completes and only reports violations, use the rule-specific skills

Compatibility

Audit agent harness on Playwright or Puppeteer. Route waits should target content selectors. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

agent route change timeout spa

Same failure, same content-based wait.

audit agent spa navigation hang

Practitioner phrasing.

the breakdown hits other routes too

Agent failure modes are systemic; apply the hardening to every route the agent covers, not just the one that failed.

Why it happens

SPA route changes are history API pushes plus a render, with no page load. Agents written for multi-page apps wait for navigation or load events, which fire immediately or not at all on client-side transitions, so the agent either scans the old view or waits until timeout. The fix is waiting for what the route actually renders: a route-specific selector, the hydration signal, or network quiet for the route's data. Each route may need its own ready selector. Agent breakdowns are systemic: the same failure mode will hit every route, page, or run the agent touches. Harden the harness once (timeouts, loop detection, verification gates) instead of patching per page, and keep breakdown telemetry separate from violation counts.

Edge cases

• Hash-based routers never even push history state cleanly, content selectors are the only reliable wait.
• Record which wait strategy succeeded per route, it becomes the route's audit profile.
• A route that never settles is a page bug, report it after the cap instead of retrying forever.
• Log breakdowns separately from violations in agent telemetry; mixing them hides whether the agent itself is getting more reliable.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstlzZyETUV5-RvG6OfWGhWA

Resolved from the public thread: https://vectle.com/posts/pstlzZyETUV5-RvG6OfWGhWA

Thread query: audit agent timed out on client-side route change

TL;DR: Wait for the route's ready signal, not the navigation event: client-side route changes do not reload the page, so load-event waits return instantly while the new view is still rendering. Have the agent wait for a route-specific selector or the hydration signal after each transition. One line of why: SPA routers swap views without navigation events, so navigation-based waits lie.