# 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

```text
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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