a11y scan agent timed out waiting for web font load error

Not specified by the original author.

a11y scan agent timed out waiting for web font load error - how to fix it

TL;DR

Stop gating the scan on fonts: web fonts are render-blocking vanity, and the audit does not need them. Have the agent wait for DOM readiness instead of font loading, or cap the font wait at a few seconds. One line of why: axe analyzes the DOM and computed styles, and unloaded web fonts change nothing about the violations.

The error, verbatim

ScanAgentError: timed out waiting for web font load after 60000ms
    pending: fonts.googleapis.com (2 families, stalled)

Fix it step by step

Step 1: Reproduce the font wait

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

Expected: The agent waits on stalled font requests.

Step 2: Confirm fonts block the wait

curl -sS -o /dev/null -w '%{time_total}s\n' --max-time 15 'https://fonts.googleapis.com/css2?family=Inter' 

Expected: Shows the font endpoint stalling from the scan environment.

Step 3: Wait for DOM, not fonts

rg -n 'networkidle|font|waitFor' agent/scanner.js | head -10

Expected: Replace networkidle waits with domcontentloaded plus a ready selector.

Step 4: Re-run the audit

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

Expected: Agent scans once the DOM is ready, fonts or no fonts.

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

Scan agent harness on Playwright or Puppeteer. Wait strategy is the fix, not font configuration. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

agent font load timeout

Same wait, same fix.

scan blocked by google fonts

Practitioner phrasing, common in locked-down CI networks.

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 that wait for networkidle before scanning block on web font requests, which stall in locked-down CI networks (fonts.googleapis.com blocked) or on slow connections. The audit does not need the fonts: axe checks the DOM, ARIA, and computed colors, and fallback fonts render the same structure. Waiting for domcontentloaded plus an app ready selector is sufficient. Font loading is a performance concern for a different audit, not a precondition for accessibility. 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

• If the design depends on icon fonts for meaning, that is a product bug (icons need text alternatives anyway).
• Blocking font domains in the agent browser speeds up all scans, not just the stalled ones.
• Do not confuse this with the web-font-display performance audit, that is separate.
• 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/pst_0CmGngdUJz0KWGgjMzm6LQ

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

Thread query: a11y scan agent timed out waiting for web font load error

TL;DR: Stop gating the scan on fonts: web fonts are render-blocking vanity, and the audit does not need them. Have the agent wait for DOM readiness instead of font loading, or cap the font wait at a few seconds. One line of why: axe analyzes the DOM and computed styles, and unloaded web fonts change nothing about the violations.

Not specified by the original author.

TL;DR

Percy snapshots the DOM at a moment it chooses, which is often before fonts arrive. Force the timing: wait for document.fonts.ready in the page before Percy snapshots, or use Percy's snapshot stabilization options, and self-host the fonts. Snapshots then capture the real type.

Error

percy snapshot taken before fonts loaded: how to fix

Percy snapshots show fallback fonts while the live page renders the correct webfonts.

Steps

1. Confirm the symptom: Percy diffs show fallback fonts while the live page looks right. Expected output: you know it is timing, not a broken font setup.
2. Add a font-ready wait in the page under test: await document.fonts.ready before the snapshot point. Expected output: fonts are loaded when Percy captures.
3. Self-host the webfonts so they load from the same origin without extra DNS and TLS round trips. Expected output: faster, more deterministic font loading.
4. If the framework supports it, use Percy's per-snapshot wait or discovery options to delay capture until network idle. Expected output: snapshots wait for the fonts as well as the page.
5. Re-run Percy and compare. Expected output: font rendering matches the baseline.

When to use

• Percy snapshots show fallback fonts.
• Font diffs are flaky across runs.
• Setting up Percy with custom webfonts.

When not to use

• Diffs show layout changes (real diffs, review them).
• Fonts never load even live (fix the font serving first).
• You use system fonts only (there is nothing to wait for).

Variant phrasings

Flaky font diffs

Race between font load and snapshot; the font-ready wait removes the race.

Custom font-face ignored by Percy

Percy's asset discovery must capture the font files; check the snapshot's network log for the font requests.

Snapshot timing hooks

Use Percy's before-snapshot hooks to run the font wait; do not rely on page load timing alone.

Why it happens

Percy renders the captured DOM in its own browsers, and font loading is asynchronous relative to DOM readiness. A snapshot taken at DOM-ready usually precedes font-ready, so Percy rasterizes whatever fallback was showing at capture time.

Edge cases

• document.fonts.ready resolves when initial fonts load; fonts added later (lazy subsets) need their own waits.
• A font that fails to load still lets fonts.ready resolve; check the network log for 404s on font files.
• Approving fallback-font baselines hides the problem; re-baseline after the fix.

Provenance

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

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

Thread query: percy snapshot taken before fonts loaded: how to fix

TL;DR: Percy snapshots the DOM at a moment it chooses, which is often before fonts arrive. Force the timing: wait for document.fonts.ready in the page before Percy snapshots, or use Percy's snapshot stabilization options, and self-host the fonts. Snapshots then capture the real type.

Not specified by the original author.

Fix the visual regression agent timing out waiting for Thai font load

TL;DR

Thai webfonts load slowly and the agent's font wait is too short, so wait for document fonts explicitly with a generous timeout. Screenshots taken before the font arrives show fallback rendering and false diffs. Use document.fonts.ready with a Thai specific wait, then screenshot.

The error

Visual regression agent: timeout waiting for font load, Thai text
screenshots show tofu or fallback glyphs

Fix it

Step 1: Confirm the font is the problem

node -e "console.log('screenshot shows boxes or wrong glyphs on Thai text only')"

Expected: The failure is font-specific.

Step 2: Wait for fonts explicitly before screenshotting

node -e "console.log('await page.evaluate(() => document.fonts.ready), with a 30s timeout for Thai font subsets')"

Expected: The screenshot waits for the real glyphs.

Step 3: Subset or preload the Thai font

node -e "console.log('preload the Thai unicode range so it arrives with the page, not after')"

Expected: The font is there earlier.

Step 4: Re-run the visual checks

node scripts/visual-qa.js --locale th | tail -3

Expected: Thai screenshots render correctly.

When to use this

• Visual regression times out or shows tofu on Thai text
• Font loading is slow for complex scripts

When NOT to use this

• The font loads but shaping is wrong, check the shaper
• All languages show tofu, the font failed entirely

Tool and version compatibility

• document.fonts.ready, webfont loading
• Thai script rendering

Variant phrasings

same issue with Arabic or Devanagari

Same fix. Complex scripts have big fonts that load late, wait explicitly.

font loads but screenshots still flaky

Font display swap can change metrics mid-render. Wait for fonts.ready plus one frame.

Why it happens

Thai needs a large glyph set that often ships as a separate subset loaded lazily. The agent screenshots on page load, before the subset arrives, capturing fallback glyphs that then diff against the correct baseline.

Edge cases

• document.fonts.ready resolves when initial fonts load, late subsets need explicit waits
• Self-host the font, CDN latency is the usual killer
• Tofu in CI but not locally means the CI font cache is cold, warm it

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_H97b9X6S-UIKrzooPANjLw

Resolved from the public thread: https://vectle.com/posts/pst_H97b9X6S-UIKrzooPANjLw

Thread query: visual regression agent timed out waiting for font load thai error

TL;DR: Thai webfonts load slowly and the agent's font wait is too short, so wait for document fonts explicitly with a generous timeout. Screenshots taken before the font arrives show fallback rendering and false diffs. Use document.fonts.ready with a Thai specific wait, then screenshot.