remotion-dev/remotion · error · TypeError

'${codec}' is not a valid codec for GCP Cloud Run. The follo

Error message

'${codec}' is not a valid codec for GCP Cloud Run. The following values are supported: ${cloudrunCodecs.join(', ')}

What it means

Thrown by validateCloudrunCodec() when codec is a string but not in the Cloud Run allow-list (h264, vp8, vp9, mp3, aac, wav, gif, prores). Cloud Run constrains codecs to those its bundled ffmpeg/encoder pipeline supports. The message lists all valid values so the caller can pick a supported one.

Source

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

	'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. Switch to one of the supported codecs: h264, vp8, vp9, mp3, aac, wav, gif, prores.
2. Use 'mp3' or 'aac' instead of audio-specific aliases like 'audio-mp3'.
3. Branch your codec config per backend if you target both Lambda and Cloud Run.

Example fix

// before
await renderMediaOnCloudRun({ codec: 'h265', ... });
// after
await renderMediaOnCloudRun({ codec: 'h264', ... });

import { validateCloudrunCodec } from '@remotion/cloudrun/shared';
validateCloudrunCodec(codec); // throws early with the supported list

const CLOUDRUN_CODECS = ['h264','vp8','vp9','mp3','aac','wav','gif','prores'] as const;
function isCloudrunCodec(v: unknown): v is typeof CLOUDRUN_CODECS[number] {
  return typeof v === 'string' && (CLOUDRUN_CODECS as readonly string[]).includes(v);
}

if (!isCloudrunCodec(codec)) throw new Error(`Unsupported codec. Use one of: ${CLOUDRUN_CODECS.join(', ')}`);

When it happens

Trigger: Passing a codec valid for local rendering or Lambda but unsupported on Cloud Run, e.g. 'h265', 'h264-mkv', 'audio-mp3' (use 'mp3' instead), or any non-listed string.

Common situations: Sharing codec config across Lambda and Cloud Run paths where the supported sets differ; copy-pasting from the Lambda docs; using a deprecated codec alias.

Related errors

• "codec" must be a string
• Bucket creation is required, but no region has been passed.
• Either cloudRunUrl or serviceName must be provided
• Either cloudRunUrl or serviceName must be provided, not both
• If determining Cloudrun Url from serviceName, region must be

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