Remotion Composition IDs: Naming Rules and Common Errors
A composition ID that looks fine to read can still fail — Remotion enforces specific character rules most people discover from an error message, not the docs.
A <Composition>'s id prop looks like a free-text string, but Remotion validates it against a specific pattern, and violating that pattern produces an error at render or Studio load time rather than at the point where you wrote the ID.
The rule
Composition IDs must contain only letters, numbers, and hyphens — no underscores, no spaces, no special characters. My_Composition and My Composition both fail validation; My-Composition passes.
Why this trips people up
Underscores are extremely common in code identifiers, so writing Wide_TermCallout or similar feels natural and passes a linter or TypeScript check without complaint — the failure only shows up when Remotion actually tries to register or render the composition, which can be well after the ID was written, in a different part of the workflow entirely.
The fix
// fails validation
<Composition id="Wide_TermCallout" ... />
// passes
<Composition id="Wide-TermCallout" ... />Simply swap underscores for hyphens. If you're also passing the ID as a CLI argument to the render command, make sure that matches exactly — case-sensitive, hyphen-for-hyphen.
Programmatically generating IDs
If your composition IDs are generated dynamically (for example, one per video variant in a batch render setup), sanitize them through a small function before registering the composition, rather than trusting that generated strings will happen to avoid invalid characters:
const safeId = (s) => s.replace(/[^a-zA-Z0-9-]/g, "-");Naming and structural rules like this are exactly the kind of thing that's easy to get wrong once, then copy forward into every new composition — a locked template only pays that cost a single time.
See the templates