remotion-dev/remotion · error · Error

${path}.text must be a string.

Error message

${path}.text must be a string.

What it means

parseCaptionFile validates each entry of a parsed captions JSON array. When element at index N is an object but its text property is not a string, the error fires with a path like captions[N].text to pinpoint the offending field in the caption file.

Source

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

	} catch (error) {
		throw new Error(
			`Invalid JSON: ${error instanceof Error ? error.message : String(error)}`,
		);
	}

	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.`);
		}

View on GitHub (pinned to b2f4e34732)

Solutions

1. Add or rename the field to `text` with a string value
2. Quote the value: text must be a JSON string, not a number
3. Re-export with the Remotion caption schema

Example fix

// before
{"text": 123, "startMs": 0, "endMs": 1000}
// after
{"text": "123", "startMs": 0, "endMs": 1000}

for (const [i, c] of parsed.entries()) {
  if (typeof (c as any).text !== 'string') {
    throw new Error(`captions[${i}].text must be a string`);
  }
}

const hasText = (c: Record<string, unknown>): c is {text: string} & Record<string, unknown> =>
  typeof c.text === 'string';

try {
  const captions = parseCaptionFile({fileName, contents});
} catch (e) {
  // retry after normalizing the flagged field
}

When it happens

Trigger: parseCaptionFile validates captions[i] and finds typeof caption.text !== 'string' — e.g. {"startMs":0,"endMs":1000} (missing text) or {"text": 123}.

Common situations: Field renamed to `body`/`content` by an exporting tool; missing text on auto-generated cues; JSON serialization turned text into a number.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Expected a Remotion Caption[] JSON array.
• ${path} must be an object.
• ${path}.startMs must be a finite, non-negative number.
• ${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/a385ecee1ee1de89. Report an issue: GitHub.