remotion-dev/remotion · error · TypeError

The "${name}" prop ${location} must be a string, but you pas

Error message

The "${name}" prop ${location} must be a string, but you passed a value of type ${typeof defaultCodec}.

What it means

`validateCodec` asserts that a codec value (the `defaultCodec` returned from `calculateMetadata`, or the `codec` passed to serverless render APIs) is a string. Passing a non-string (number, object, etc.) throws a TypeError before the codec-list membership check runs. `undefined` is allowed and returns early (meaning 'use default').

Source

Thrown at packages/core/src/validation/validate-default-codec.ts:14

import type {Codec, CodecOrUndefined} from '../codec';
import {validCodecs} from '../codec';

export function validateCodec(
	defaultCodec: unknown,
	location: string,
	name: string,
): asserts defaultCodec is CodecOrUndefined {
	if (typeof defaultCodec === 'undefined') {
		return;
	}

	if (typeof defaultCodec !== 'string') {
		throw new TypeError(
			`The "${name}" prop ${location} must be a string, but you passed a value of type ${typeof defaultCodec}.`,
		);
	}

	if (!validCodecs.includes(defaultCodec as Codec)) {
		throw new Error(
			`The "${name}" prop ${location} must be one of ${validCodecs.join(
				', ',
			)}, but you passed ${defaultCodec}.`,
		);
	}
}

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Ensure the codec value is a string literal or a properly typed variable.
2. Coerce env/config sources: `const codec = String(config.codec)`.
3. Return `undefined` (or omit the key) to use the default codec instead of a non-string.
4. Type the function return as `Codec | undefined` so TypeScript catches it.

Example fix

// before
calculateMetadata: () => ({defaultCodec: 264, ...})
// after
calculateMetadata: () => ({defaultCodec: 'h264', ...})

if (codec !== undefined && typeof codec !== 'string') {
  throw new TypeError('codec must be a string or undefined');
}

const isCodecString = (c) => c === undefined || typeof c === 'string';

When it happens

Trigger: Returning `defaultCodec` from a `calculateMetadata` callback as a non-string (e.g. a number, an object, or a mis-typed enum); or calling `renderMediaOnLambda`/`renderMedia` with `codec` set to a non-string value.

Common situations: Reading codec from an env var or CLI arg without coercion (`process.env.CODEC` that is sometimes parsed as a number); a JSON config that stores codec as an object `{name:'h264'}`; a refactor that changes the shape of the returned metadata.

Related errors

• The "${name}" prop ${location} must be one of ${validCodecs.
• The "${nameOfProp}" prop ${location} must be a number, but y
• "codec" must be a string
• '${codec}' is not a valid codec for GCP Cloud Run. The follo
• The "content" must be a string or Uint8Array, but you passed

AI-assisted analysis of remotion-dev/remotion@78fe4bb3fd (2026-08-12). Data as JSON: /api/errors/de452170a7ab5f93. Report an issue: GitHub.