# fix agent timed out waiting for cms preview render - how to fix it

## TL;DR

Decouple verification from the CMS preview: have the agent verify patches against a local render or the staging build instead of waiting on the CMS preview iframe. CMS previews are slow, flaky, and session-gated. One line of why: the agent needs a render to verify against, and the CMS preview is the worst available render.

## The error, verbatim

```text
FixAgentError: timed out waiting for CMS preview render after 300s
    cms: preview iframe never fired load (session expired in iframe)
    patch: unverified, held

```

## Fix it step by step

### Step 1: Reproduce the preview wait

```bash
node agent/remediate.js --verify preview | rg -i 'preview|timed out' | head -5
```

Expected: The agent blocks on the CMS preview iframe.

### Step 2: Confirm the preview is the bottleneck

```bash
node -e "console.log('preview iframe: session-gated, 5min+ cold render, flakes 30 percent')"
```

Expected: The preview environment is the problem, not the patch.

### Step 3: Verify against staging instead

```bash
rg -n 'preview|verify' agent/remediate.js | head -10
```

Expected: Change verification to deploy the patch to a staging branch and scan there.

### Step 4: Re-run remediation

```bash
node agent/remediate.js | tail -4
```

Expected: Patches verify against staging renders and land without CMS waits.

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

Fix agent with staging deploy verification. CMS preview iframes are the thing being routed around. Pin the tool version in the lockfile so scans stay reproducible across machines.

## Variant phrasings

### agent cms preview timeout

Same wait, same decoupling.

### fix agent blocked by preview render

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

CMS-driven sites tempt agents to verify patches in the CMS preview, but previews are session-gated iframes with cold renders and flaky loads. The agent waits, the session expires, the iframe never loads, the patch stays unverified. Staging builds (or local renders) are faster, more reliable, and closer to production. The patch pipeline should be source to staging to scan, with the CMS preview reserved for human content review, not agent verification. 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 CMS is the only render path, warm the preview session before the run and bound the wait.
- Preview-only components still need a scan path, push for a staging equivalent.
- Record which render the patch was verified against, preview-verified and staging-verified are different claims.
- 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_h5nEFQzpmdc5yzOFfRMGVw