Handling Rendering Errors

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:

{
  "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:

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:

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:

{
  "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

Essentials

Managing Templates

Rendering Jobs

Fonts Management

Where Errors Appear

Webhook Delivery

Manual Polling

Common Causes of Render Failures

Debugging Strategy

Inspect the Template First

Use Preview Mode

Isolate with a Minimal Payload

Best Practices for Stability

​Where Errors Appear

​Webhook Delivery

​Manual Polling

​Common Causes of Render Failures

​Debugging Strategy

​Inspect the Template First

​Use Preview Mode

​Isolate with a Minimal Payload

​Best Practices for Stability

Where Errors Appear

Webhook Delivery

Manual Polling

Common Causes of Render Failures

Debugging Strategy

Inspect the Template First

Use Preview Mode

Isolate with a Minimal Payload

Best Practices for Stability