remotion-dev/remotion · error · Error

${path}.startMs is out of timestamp order.

Error message

${path}.startMs is out of timestamp order.

What it means

parseCaptionFile validates that captions parsed from a caption file (e.g. SRT/VTT style input) have non-decreasing start times. When a caption's startMs is earlier than the startMs of the previous caption, parsing is aborted with this error. Remotion requires strictly ordered timestamps so that captions can be rendered in a predictable sequence.

Source

Thrown at packages/studio/src/components/parse-caption-file.ts:83

		if (
			typeof caption.confidence === 'number' &&
			(caption.confidence < 0 || caption.confidence > 1)
		) {
			throw new Error(`${path}.confidence must be between 0 and 1.`);
		}

		if (
			caption.pageBreakAfter !== undefined &&
			typeof caption.pageBreakAfter !== 'boolean'
		) {
			throw new Error(
				`${path}.pageBreakAfter must be a boolean when provided.`,
			);
		}

		if (previousStart !== null && caption.startMs < previousStart) {
			throw new Error(`${path}.startMs is out of timestamp order.`);
		}

		previousStart = caption.startMs;
	}

	return parsed as Caption[];
};

View on GitHub (pinned to b2f4e34732)

Solutions

1. Sort the captions by startMs before passing them to parseCaptionFile (or fix the source file so cues are chronological).
2. Verify the caption file itself: open it and confirm each cue's timestamp is >= the previous cue's timestamp.
3. If merging multiple caption sources, merge-sort them by startMs instead of concatenating.
4. If the caption genuinely starts earlier (overlapping speech), split or shift the cue so startMs respects the ordering rule.

Example fix

// before
parseCaptionFile(captions);
// after
parseCaptionFile([...captions].sort((a, b) => a.startMs - b.startMs));

const sorted = captions.every((c, i, a) => i === 0 || c.startMs >= a[i - 1].startMs);
if (!sorted) throw new Error('captions are not in startMs order');

const isInOrder = (cs: {startMs: number}[]) => cs.every((c, i, a) => i === 0 || c.startMs >= a[i - 1].startMs);

try {
  const parsed = parseCaptionFile(file);
} catch (e) {
  if (e.message.includes('out of timestamp order')) {
    captions.sort((a, b) => a.startMs - b.startMs);
  } else throw e;
}

When it happens

Trigger: Calling parseCaptionFile on a caption array/file whose entries are not sorted by startMs; manually constructed Caption arrays passed in out of order; caption files with overlapping or shuffled cues.

Common situations: Hand-edited caption files, captions exported from a transcription tool that interleaves speakers, or programmatically built caption lists appended in the wrong order.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Invalid timestamp:${time}
• Invalid ElevenLabs transcript. The transcript must be genera
• Cannot interpolate "${value}" because horizontal transform-o
• outputPath must be a string.
• ${outputError}

AI-assisted analysis of remotion-dev/remotion@b2f4e34732 (2026-09-09). Data as JSON: /api/errors/6f0fd8bc73531b41. Report an issue: GitHub.