# audit agent hung waiting for lazy-loaded iframe - how to fix it

## TL;DR

Stop waiting on iframes that never load: give each iframe a load deadline, and when it expires, audit the page without that frame and note the gap. Lazy iframes below the fold may never load until scrolled to. One line of why: the agent cannot distinguish a broken iframe from a lazy one, so it must bound the wait and report either way.

## The error, verbatim

```text
AuditAgentError: hung waiting for lazy iframe load after 90s
    iframe: #comments-frame (loading=lazy, below fold)

```

## Fix it step by step

### Step 1: Reproduce the hang

```bash
node agent/run-audit.js --route /article | rg -i 'iframe|hung' | head -5
```

Expected: The agent hangs on the lazy comments iframe.

### Step 2: Check the iframe attributes

```bash
curl -s https://example.com/article | rg -c 'iframe'
```

Expected: Counts iframe elements; check the markup for loading=lazy attributes.

### Step 3: Add per-iframe deadlines

```bash
rg -n 'iframe' agent/scanner.js | head -10
```

Expected: Add: 15s per-iframe deadline, then proceed without it and record the gap.

### Step 4: Re-run the audit

```bash
node agent/run-audit.js --route /article | tail -4
```

Expected: Agent proceeds past the lazy iframe and completes the audit with a noted gap.

### 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

Audit agent harness with iframe load tracking. Deadlines are per-frame, not global. Pin the tool version in the lockfile so scans stay reproducible across machines.

## Variant phrasings

### agent hung on iframe load

Same hang, same deadline fix.

### lazy iframe blocks audit

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

Lazy-loaded iframes (comments, embeds) only load when scrolled into view, but agents that wait-for-all-frames block forever on viewports that never scroll there. Worse, some iframes fail silently (blocked third party) and never fire load at all. A per-iframe deadline with a recorded gap turns a hang into a partial audit with known coverage. Scrolling each iframe into view before the deadline is a reasonable first try, but the deadline must exist regardless. 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

- Scroll lazy iframes into view once before starting the deadline, many then load promptly.
- Record unaudited iframes in the report, a silent skip is a false clean.
- Third-party iframes blocked by ad blockers in the agent browser need an allowlist decision, not longer waits.
- 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_EgAxMmDfwzOcGE00WrD3uQ