# agent timed out waiting for merge field preview render: how to fix it

An agent timing out on merge field preview render needs the same async treatment as any slow render: trigger, poll, and only then read the result. Preview renders can be slow on complex templates, and a fixed short wait loses the race.

```text
agent timed out waiting for merge field preview render
```

## When to use this skill
- Agent merge preview waits time out
- Complex templates time out while simple ones pass

## When not to use this skill
- Previews fail fast with errors (a template issue)
- The renderer is down (a platform issue)

## Tool compatibility
Agent merge field preview rendering.
Related area: agent frameworks and agent runtime tooling.
Cloud UIs change labels over time; if a button moved, search settings for the closest match.

## Before you start
- Sign in to the tool and keep one tab open so sessions stay clean
- Copy the exact error text and note the time it happened
- Set aside 15 to 20 minutes; most of these resolve in a single pass

## Quick diagnosis
Make sure this is the right skill before you invest the 15 minutes.
- If you are dealing with agent merge preview waits time out, start at step 1 below.
- If instead previews fail fast with errors (a template issue), stop here; you need a different skill.
- If neither quite matches, compare your screen against the verbatim error block at the top; that block is exactly what this skill covers.

## Fix it in steps
### 1. Trigger the preview and poll

```
Start the render, then check readiness on an interval.
```
Expected: no single wait long enough to time out.

### 2. Simplify the test case

```
Preview with a minimal record first to check renderer health.
```
Expected: fast preview confirms the renderer works.

### 3. Allow more time for complex templates

```
Extend the polling deadline for templates with many fields.
```
Expected: slow renders complete within budget.

### 4. Cache preview results

```
Reuse preview output within the run instead of re-rendering.
```
Expected: fewer renders and faster runs.

## Confirm each step worked
Run through this checklist before moving on. If a check fails, redo that step instead of pushing ahead.
- Step 1 (trigger the preview and poll): Expected: no single wait long enough to time out.
- Step 2 (simplify the test case): Expected: fast preview confirms the renderer works.
- Step 3 (allow more time for complex templates): Expected: slow renders complete within budget.
- Step 4 (cache preview results): Expected: fewer renders and faster runs.

## Quick recap
1. Trigger the preview and poll
2. Simplify the test case
3. Allow more time for complex templates
4. Cache preview results

## Still stuck?
Gather three things: the exact error text, the time it happened, and what changed just before it broke.
Check the vendor status page for an active incident. Then open a support ticket with those three things;
it cuts the back-and-forth in half. For agent runs, attach the last 50 lines of the agent log too,
since the loop or timeout signature in the log usually names the cause.

## Variant phrasings
### merge preview render timeout agent
Poll instead of waiting once. If this matches what you saw, the steps above apply as written.

### agent waiting for merge preview
Complex templates need longer polling budgets. If this matches what you saw, the steps above apply as written.

## Why it happens
Preview renders run server-side with duration tied to template complexity. A fixed client wait either times out on complex templates or wastes time on simple ones, while polling adapts to the actual render time.

## Edge cases
- Preview with real data, minimal records can hide field errors
- Poll gently to avoid hammering the render queue
- Log render times to spot template regressions

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_xdTalE-DkMYhQonGCHZu0w