remotion-dev/remotion · error · Error

${path}.pageBreakAfter must be a boolean when provided.

Error message

${path}.pageBreakAfter must be a boolean when provided.

What it means

parseCaptionFile treats pageBreakAfter as optional, but if it is provided it must be a strict boolean. Passing truthy/non-boolean values such as 1, 'true', or null is rejected while validating the indexed caption.

Source

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

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

		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. Change the value to a real JSON boolean: true or false (unquoted)
2. Remove the field entirely if not needed (undefined is allowed)
3. Fix the exporter to serialize booleans as booleans

Example fix

// before
{"text": "hi", "startMs": 0, "endMs": 1000, "pageBreakAfter": "true"}
// after
{"text": "hi", "startMs": 0, "endMs": 1000, "pageBreakAfter": true}

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

const isOptionalBoolean = (v: unknown): v is boolean | undefined =>
  v === undefined || typeof v === 'boolean';

try {
  const captions = parseCaptionFile({fileName, contents});
} catch (e) {
  // coerce "true"/1 to boolean or drop the field, retry
}

When it happens

Trigger: captions[i].pageBreakAfter is defined but typeof !== 'boolean', e.g. pageBreakAfter: "true", 0, or 1.

Common situations: Tools serializing booleans as strings or 0/1 integers; hand-editing the JSON with "true" quoted; config-driven generation using truthy flags.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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

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