remotion-dev/remotion · error · Error

.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.

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));
Defensive patterns

Strategy: validation

Validate before calling

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');

Type guard

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

Try / catch

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;
}

Prevention

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


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

Appendix: 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)