Handling Rendering Errors

Learn how to handle rendering errors and avoid them

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:

"status": "failed"

You can detect this in two ways:

Webhook Delivery

If you’ve defined a webhook, the error will be delivered as a POST request:

{
  "id": "01JTRDF7HCR8QAHYW8GPCP4S9Y",
  "status": "failed",
  "error": {
    "message": "Layer 'title' not found in composition 'main'",
    "code": "LAYER_NOT_FOUND"
  }
}

Manual Polling

Use the jobs API:

  curl -X GET https://api.nexrender.com/api/v2/jobs/JOB_ID \
    -H "Authorization: Bearer YOUR_API_KEY"

Check the returned status and error fields.

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 name when submitting job
Missing asset URL	Asset failed to download (403)	Double-check src links or permissions
Font not found	Font 'CustomFont-Bold.ttf' not available	Preload 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

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

Debugging Strategy

Inspect the Template

Use the GET /templates/:id endpoint to see:

• Available compositions
• All dynamic layers + property names
• Font dependencies (if visible)

  curl -X GET https://api.nexrender.com/api/v2/templates/TEMPLATE_ID \
    -H "Authorization: Bearer YOUR_API_KEY"

Use Preview Mode

Render the job with "preview": true:

  {
    "template": { "id": "...", "composition": "main" },
    "preview": true
  }

This saves time and cost — and reveals most issues (missing layers, layout bugs, expression crashes) before final rendering.

Test Job Payloads with Defaults

Temporarily reduce your job to a minimal payload with:

• Static text only
• No image/audio layers
• Known good composition

Once that succeeds, reintroduce dynamic elements incrementally.

Best Practices for Stability

• Fetch template metadata before every job
• Use meaningful layerNames and document them internally
• Preload fonts instead of assuming they exist
• Validate URLs before sending render jobs
• Wrap asset layers with fallback expressions inside AE
• Enable webhook retries on your server (at least 3 attempts)