What causes "outputPath must be a string." in remotion-dev/remotion?

Pass outputPath as a plain string (e.g. "captions.srt")

outputPath must be a string.

Error message

outputPath must be a string.

What it means

The optional `outputPath` input, if supplied, must be a string. When omitted, the tool derives a default caption file name via getDefaultCaptionOutputName(). Non-string outputPath values are rejected before the output name is validated.

Source

Thrown at packages/studio/src/components/WebMcp.tsx:597

						}

						const forceFullSequences = input.forceFullSequences ?? false;
						const doSample = input.doSample ?? false;
						if (
							typeof forceFullSequences !== 'boolean' ||
							typeof doSample !== 'boolean'
						) {
							throw new Error(
								'forceFullSequences and doSample must be booleans.',
							);
						}

						const src = staticFile(assetPath);
						const displayName = assetPath.split('/').at(-1) ?? assetPath;
						const outputPath =
							input.outputPath ?? getDefaultCaptionOutputName(src, displayName);
						if (typeof outputPath !== 'string') {
							throw new Error('outputPath must be a string.');
						}

						const outputError = validateCaptionOutputName(outputPath);
						if (outputError !== null) {
							throw new Error(outputError);
						}

						const jobId = addCaptionJob({
							audioStreamIndex: null,
							chunkLengthInSeconds,
							displayName,
							doSample,
							forceFullSequences,
							language: model.multilingual ? language : null,
							model: model.name,
							noRepeatNgramSize,
							outName: outputPath,
							repetitionPenalty,

View on GitHub (pinned to b2f4e34732)

Solutions

Pass outputPath as a plain string (e.g. "captions.srt")
Omit outputPath to let the tool generate a default name
Stringify/normalize the value before calling

Example fix

// before
{ "outputPath": { "path": "out.srt" } }
// after
{ "outputPath": "out.srt" } // or omit entirely

Defensive patterns

Strategy: type-guard

Validate before calling

if (input.outputPath !== undefined && typeof input.outputPath !== 'string') {
  throw new Error('outputPath must be a string');
}

Type guard

const isOutputPath = (v: unknown): v is string => typeof v === 'string';

Try / catch

try {
  await callWhisperTool({ outputPath });
} catch (err) {
  if (err instanceof Error && err.message === 'outputPath must be a string.') {
    await callWhisperTool({}); // let the tool derive a default name
  }
}

Prevention

Pass plain string paths, not Path objects or nested objects
Omit outputPath to accept the auto-generated caption file name
Stringify user input before sending

When it happens

Trigger: Passing input.outputPath as an object, array, number, or boolean instead of a string file name/path.

Common situations: Passing a filesystem Path object from another tool; accidentally nesting the value (e.g. { path: "out.srt" }); form data serializing as non-string.

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

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