remotion-dev/remotion · error · Error

Unsupported caption file. Choose a .json file.

Error message

Unsupported caption file. Choose a .json file.

What it means

Thrown by parseCaptionFile in Remotion Studio when the selected caption file does not end (case-insensitively) with '.json'. Only JSON caption files in Remotion's Caption[] format can be imported through this path.

Source

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

import type {Caption} from '@remotion/captions';

const isObject = (value: unknown): value is Record<string, unknown> => {
	return typeof value === 'object' && value !== null && !Array.isArray(value);
};

const isFiniteNumber = (value: unknown): value is number => {
	return typeof value === 'number' && Number.isFinite(value);
};

export const parseCaptionFile = ({
	fileName,
	contents,
}: {
	fileName: string;
	contents: string;
}): Caption[] => {
	if (!fileName.toLowerCase().endsWith('.json')) {
		throw new Error('Unsupported caption file. Choose a .json file.');
	}

	let parsed: unknown;
	try {
		parsed = JSON.parse(contents);
	} 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}]`;

View on GitHub (pinned to b2f4e34732)

Solutions

1. Convert the file to Remotion's JSON Caption[] format and use the .json extension.
2. Rename/verify the file extension is .json (content must also be valid JSON).
3. Use a converter (e.g. from SRT/VTT to Remotion captions) before importing.

Example fix

// before
parseCaptionFile({ fileName: 'captions.srt', contents })
// after
parseCaptionFile({ fileName: 'captions.json', contents: JSON.stringify(captions) })

if (!fileName.toLowerCase().endsWith('.json')) {
  throw new Error('Convert captions to .json first');
}

const isJsonCaptionFile = (name: string): boolean => name.toLowerCase().endsWith('.json');

try { parseCaptionFile({fileName, contents}); } catch (e) { if (String(e.message).includes('Unsupported caption file')) { /* convert SRT/VTT to JSON */ } else throw e; }

When it happens

Trigger: Selecting or passing a .srt, .vtt, .txt, or extensionless file to parseCaptionFile.

Common situations: Users exporting captions from editors as SRT/VTT and dragging them into Studio, expecting automatic conversion.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• Invalid timestamp:${time}
• Invalid ElevenLabs transcript. The transcript must be genera
• outputPath must be a string.
• ${outputError}
• Expected a Remotion Caption[] JSON array.

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