remotion-dev/remotion · error · Error

${path}.startMs must be a finite, non-negative number.

Error message

${path}.startMs must be a finite, non-negative number.

What it means

parseCaptionFile requires each caption's startMs to be a finite, non-negative number (checked with isFiniteNumber). NaN, Infinity, negative values, or missing/non-numeric startMs fields in a captions JSON file trigger this error, reported with the index path of the offending caption.

Source

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

	}

	if (!Array.isArray(parsed)) {
		throw new Error('Expected a Remotion Caption[] JSON array.');
	}

	let previousStart: number | null = null;
	for (const [index, caption] of parsed.entries()) {
		const path = `captions[${index}]`;
		if (!isObject(caption)) {
			throw new Error(`${path} must be an object.`);
		}

		if (typeof caption.text !== 'string') {
			throw new Error(`${path}.text must be a string.`);
		}

		if (!isFiniteNumber(caption.startMs) || caption.startMs < 0) {
			throw new Error(`${path}.startMs must be a finite, non-negative number.`);
		}

		if (!isFiniteNumber(caption.endMs) || caption.endMs < 0) {
			throw new Error(`${path}.endMs must be a finite, non-negative number.`);
		}

		if (caption.endMs < caption.startMs) {
			throw new Error(`${path}.endMs must not be earlier than startMs.`);
		}

		if (caption.timestampMs !== null && !isFiniteNumber(caption.timestampMs)) {
			throw new Error(`${path}.timestampMs must be a finite number or null.`);
		}

		if (caption.confidence !== null && !isFiniteNumber(caption.confidence)) {
			throw new Error(`${path}.confidence must be a finite number or null.`);
		}

View on GitHub (pinned to b2f4e34732)

Solutions

1. Convert times to milliseconds as numbers: 1.5s -> 1500
2. Set startMs to a non-negative finite number
3. Fix the negative value from the transcription source

Example fix

// before
{"text": "hi", "startMs": "00:00:01.500", "endMs": 2000}
// after
{"text": "hi", "startMs": 1500, "endMs": 2000}

for (const [i, c] of parsed.entries()) {
  const s = (c as any).startMs;
  if (typeof s !== 'number' || !Number.isFinite(s) || s < 0) {
    throw new Error(`captions[${i}].startMs must be a finite non-negative number`);
  }
}

const isValidStartMs = (v: unknown): v is number =>
  typeof v === 'number' && Number.isFinite(v) && v >= 0;

try {
  const captions = parseCaptionFile({fileName, contents});
} catch (e) {
  // convert seconds/timestamps to ms and retry
}

When it happens

Trigger: captions[i].startMs is absent, a string like "1.5", NaN, Infinity, or < 0 — detected by !isFiniteNumber(caption.startMs) || caption.startMs < 0.

Common situations: Times exported in seconds or "00:00:01,500" string format instead of milliseconds; timestamp of -1 from a buggy transcriber; missing field from a hand-written file.

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

• Expected a Remotion Caption[] JSON array.
• ${path} must be an object.
• ${path}.text must be a string.
• ${path}.endMs must be a finite, non-negative number.
• ${path}.endMs must not be earlier than startMs.

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