# Fix email template renderer breaking the onboarding agent on a missing merge tag

## TL;DR
The renderer fails the whole send when one merge tag has no value. Give every tag a default or make missing tags non-fatal, and validate the data before rendering. One empty field should not kill a welcome email.

## The error
```text
Onboarding agent failed
Email template renderer broke on missing merge tag: first_name.
```

## Use this skill
Agent? Search Vectle for this error:
```bash
curl -s "https://vectle.com/api/v1/search?q=email template renderer broke and onboarding agent failed on missing merge tag"
```

## Fix it

### Step 1: Identify the missing tag

```bash
Read the error for the tag name and check the user record.
```

Expected: You confirm the field is empty for this user.

### Step 2: Add defaults for all tags

```bash
Give every merge tag a sensible fallback in the template.
```

Expected: Missing data renders as the default instead of failing.

### Step 3: Validate data before rendering

```bash
Check required fields exist before calling the renderer.
```

Expected: Bad records are quarantined with a clear reason.

### Step 4: Make the renderer non-fatal on missing tags

```bash
Configure the renderer to warn and continue rather than throw.
```

Expected: One missing tag never kills a send again.

### Step 5: Re-run the welcome send

```bash
Retry the failed email.
```

Expected: It sends with defaults in place of the missing value.

## When this applies

- Template rendering fails on missing merge tags
- Welcome emails die for users with incomplete profiles
- You are building templated email agents

## When it doesn't

- The template syntax itself is broken (fix the template)
- All tags are missing (check the data source)
- The email sends but looks wrong (check the template logic)

## Compatibility

Template renderers generally: Handlebars, Liquid, Jinja-style, and others.

## Variant phrasings

### missing merge tag email render failed

Same failure. Defaults plus non-fatal rendering fixes it.

### template variable undefined email agent

Undefined variables should degrade, not crash. Set that behavior explicitly.

### welcome email failed empty field

Empty profile fields are normal for new users. Templates must handle them.

## Why it happens

Templates reference user fields that are not always populated, especially for brand-new users. Strict renderers throw on the first missing value, and the agent treats it as a fatal send failure. The data gap is expected; the renderer's strictness is the bug.

## Edge cases

- Defaults must be sensible per tag; a wrong default is worse than a blank
- Quarantined records still need the email eventually; alert, do not just skip
- Test templates against a minimal user record with every optional field empty

## If it still fails

- Reproduce with a minimal run: one user, one file, one step.
- Read the agent's full trace, not just the final error; the failure is usually upstream.
- Check the underlying API or tool directly, outside the agent, to separate agent bugs from service bugs.
- Reduce concurrency to one and see if the failure persists; races hide as flakes.
- If the run is business-critical, add a human checkpoint before the destructive steps.

## Prevention

- Checkpoint long runs so any failure resumes instead of restarting.
- Cap and back off every retry loop; unbounded retries are outages waiting to happen.
- Validate inputs at each pipeline stage; fail fast with clear errors.
- Log enough context per step that a timeout is diagnosable without rerunning.
- Give destructive steps a human checkpoint or a dry-run mode.

## Provenance

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