remotion-dev/remotion · error · TypeError

"codec" must be a string

Error message

"codec" must be a string 

What it means

Thrown by validateCloudrunCodec() when the codec argument is not a string (note the trailing space in the message, a cosmetic bug). This is the type guard before the codec allow-list check. Cloud Run supports a fixed subset of codecs, so a non-string value cannot be validated further.

Source

Thrown at packages/cloudrun/src/shared/validate-gcp-codec.ts:16

const cloudrunCodecs = [
	'h264',
	'vp8',
	'vp9',
	'mp3',
	'aac',
	'wav',
	'gif',
	'prores',
] as const;

export type CloudrunCodec = (typeof cloudrunCodecs)[number];

export const validateCloudrunCodec = (codec: unknown): CloudrunCodec => {
	if (typeof codec !== 'string') {
		throw new TypeError('"codec" must be a string ');
	}

	if (!(cloudrunCodecs as readonly string[]).includes(codec)) {
		throw new TypeError(
			"'" +
				codec +
				"' is not a valid codec for GCP Cloud Run. The following values are supported: " +
				cloudrunCodecs.join(', '),
		);
	}

	if (codec === 'h264-mkv') {
		throw new Error(
			'The "h264-mkv" codec for renderMediaOnCloudrun() is deprecated - it\'s now just "h264".',
		);
	}

	return codec as CloudrunCodec;

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Pass an explicit codec string from the supported list: h264, vp8, vp9, mp3, aac, wav, gif, prores.
2. Default codec to 'h264' if your config does not specify one.
3. Validate config at startup before invoking renderMediaOnCloudRun().

Example fix

// before
const { CODEC } = process.env; // undefined
await renderMediaOnCloudRun({ codec: CODEC, ... });
// after
const codec = process.env.CODEC ?? 'h264';
await renderMediaOnCloudRun({ codec, ... });

import { validateCloudrunCodec } from '@remotion/cloudrun/shared';
validateCloudrunCodec(codec);

function isCodecString(v: unknown): v is string {
  return typeof v === 'string';
}

const codec = typeof inputCodec === 'string' ? inputCodec : 'h264';

When it happens

Trigger: Passing a non-string codec (undefined, null, number) to renderMediaOnCloudRun(), or reading codec from config where it is unset.

Common situations: Codec sourced from an env var or JSON config that omits the value; passing an options object where a string was expected.

Related errors

• 'bucketName' must be a string, but is ${JSON.stringify(bucke
• "cloudRunUrl" parameter must be a string, but is ${JSON.stri
• '${codec}' is not a valid codec for GCP Cloud Run. The follo
• Privacy must be a string
• The 'project-id' argument must be a string, but is ${JSON.st

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