Rendering failures in Shotstack typically stem from two areas: asset accessibility or JSON configuration errors.
If your render status returns FAILED, use the following checklist to identify and fix the root cause.
1. Asset Accessibility & Source Issues
The rendering engine must be able to download every file in your timeline. If a single asset is unreachable, the entire job will fail.
Public Accessibility: Ensure all
srcURLs are publicly accessible. If you use signed S3 URLs or private cloud storage, verify they haven't expired before the render starts.Unsupported File Formats: Confirm that your assets use supported codecs and containers (e.g., MP4, MOV, JPG, PNG, MP3).
Faulty Codecs (Audio/Video Stutter): If a render fails or has artifacts, the source file may have a variable frame rate or an irregular codec.
The Fix: Use the
"transcode": trueproperty within the asset object to re-encode the file into an edit-ready format before rendering.
2. JSON Payload Validation
Small syntax errors or missing required properties can break the render process.
Missing Required Attributes: For example, a
shapeasset must have a validfillcolor (e.g.,#FF5733).Timing Overlaps: Ensure your
startandlengthvalues are correct. A clip cannot have alengththat exceeds the actual duration of the source file.JSON Schema Compliance: Always validate your payload against the official Shotstack structure.
Reference: Shotstack API JSON Schemas
3. Common Error Identifiers
When a render fails, check the data.response.error message in the API response:
Error Type | Common Cause |
Download Error | The engine could not reach the |
Unsupported Format | The file type is not recognized by the engine. |
Invalid Parameter | A value (like a hex code or font name) is formatted incorrectly. |
Final Checklist for Successful Renders
To prevent rendering failures and ensure a smooth export process:
Validate Asset URLs: Double-check that all linked assets are active, accurate, and publicly accessible.
Review JSON Payload Configuration: Inspect all attributes, especially shape configurations, for completeness and accuracy.
Test Your Payload Before Submission: Use Shotstack’s validation tools (api playground) or other JSON validators to confirm there are no errors in the structure or content of your payload.
Use the Ingest API: For unreliable source files, always enable
transcode: trueto let Shotstack standardize the media first.
By addressing these areas, you can minimize the risk of rendering failures in Shotstack and improve the reliability of your projects.
If you continue to experience issues, consider reaching out to Shotstack Support with details about your payload and error messages for further assistance.