> ## Documentation Index
> Fetch the complete documentation index at: https://www.nexrender.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Handling Rendering Errors

> Learn how to detect, interpret, and fix common render job failures in Nexrender Cloud

Even the best-built templates can fail - especially when working with automation, dynamic data, and After Effects. This guide explains how to detect, interpret, and fix common job errors in Nexrender Cloud.

## Where Errors Appear

When a render job fails, the system sets its status to `"error"`. You can detect this in two ways:

### Webhook Delivery

If you've defined a webhook, the error will be delivered as a POST request to your endpoint:

```json theme={null}
{
  "id": "01JTRDF7HCR8QAHYW8GPCP4S9Y",
  "status": "error",
  "stats": {
    "errorAt": "2025-08-14T09:12:45.799Z",
    "error": "Layer 'title' not found in composition 'main'"
  }
}
```

### Manual Polling

Poll `GET /jobs/{id}` and check the `status` field:

```bash theme={null}
curl -X GET https://api.nexrender.com/api/v2/jobs/JOB_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```

When the job has failed, the response will include `"status": "error"` and a `stats.error` string describing what went wrong.

## Common Causes of Render Failures

| Cause               | Error Message Example                        | How to Fix                                             |
| ------------------- | -------------------------------------------- | ------------------------------------------------------ |
| Invalid `layerName` | `Layer 'subtitle' not found`                 | Check actual layers via `GET /templates/{id}`          |
| Missing composition | `Composition 'main' not found`               | Verify the composition name via template introspection |
| Missing asset URL   | `Asset failed to download (403)`             | Double-check `src` links and access permissions        |
| Font not found      | `Font 'CustomFont-Bold.ttf' not available`   | Preload the font using the Fonts API                   |
| Broken AE project   | `Render failed: AE crashed with exit code 1` | Preview manually inside After Effects                  |
| Expression failure  | `After Effects expression error at line X`   | Sanitize all dynamic input before injecting            |

Most errors are caused by bad data or structural mismatches between the template and the job payload.

## Debugging Strategy

### Inspect the Template First

Use `GET /templates/{id}` to see available compositions, layer names, and properties before submitting a job:

```bash theme={null}
curl -X GET https://api.nexrender.com/api/v2/templates/TEMPLATE_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```

This lets you verify exact layer names and composition names before your job runs.

### Use Preview Mode

Render the job with `"preview": true` to get a fast, low-resolution output that reveals most structural issues before committing to a full render:

```json theme={null}
{
  "template": { "id": "YOUR_TEMPLATE_ID", "composition": "main" },
  "preview": true
}
```

Preview mode catches missing layers, layout bugs, and expression crashes cheaply.

### Isolate with a Minimal Payload

Temporarily reduce your job to the simplest possible payload:

* Static text only
* No image or audio layers
* Known-good composition name

Once that succeeds, reintroduce dynamic elements one at a time until you find the failure point.

## Best Practices for Stability

* Fetch template metadata via `GET /templates/{id}` before building any job payload
* Use descriptive, unique `layerName` values and document them alongside the template
* Preload all fonts via the Fonts API before submitting jobs that reference them
* Validate all asset URLs return `200 OK` before sending a render job
* Wrap dynamic layers with fallback expressions inside After Effects
* Make your webhook handler idempotent and log every incoming payload for auditability