remotion-dev/remotion · error · TypeError

The 'siteName' argument must be a string if provided, but is

Error message

The 'siteName' argument must be a string if provided, but is ${JSON.stringify(siteName)}

What it means

Thrown by validateSiteName() in @remotion/cloudrun when siteName is provided but is not a string. The validator allows undefined (siteName is optional and returns early in that case), but any other non-string type is rejected before the name is used to address a GCS site.

Source

Thrown at packages/cloudrun/src/shared/validate-site-name.ts:9

const VALID_SITE_NAME_RE = /^[-0-9a-zA-Z!_.*'()]+$/;

export const validateSiteName = (siteName: unknown) => {
	if (typeof siteName === 'undefined') {
		return;
	}

	if (typeof siteName !== 'string') {
		throw new TypeError(
			`The 'siteName' argument must be a string if provided, but is ${JSON.stringify(
				siteName,
			)}`,
		);
	}

	if (siteName === '.' || siteName === '..') {
		throw new Error(
			'The `siteName` must not be `.` or `..`. You passed: ' + siteName + '.',
		);
	}

	if (!VALID_SITE_NAME_RE.test(siteName)) {
		throw new Error(
			'The `siteName` must match the RegExp `/' +
				VALID_SITE_NAME_RE.source +
				'/`. You passed: ' +
				siteName +

View on GitHub (pinned to 78fe4bb3fd)

Solutions

If the site name is optional, omit the field entirely (or pass undefined) rather than null.
Pass the string name returned by deploySite().
Coerce or validate upstream: typeof siteName === 'undefined' || typeof siteName === 'string'.

Example fix

// before
deploySite({ siteName: config.site ?? null, ... });

// after
deploySite({ ...(config.site ? { siteName: config.site } : {}), ... });

Defensive patterns

Strategy: type-guard

Validate before calling

if (siteName !== undefined && typeof siteName !== 'string') {
  throw new TypeError('siteName must be a string when provided');
}

Type guard

const isOptionalSiteName = (
  v: unknown,
): v is string | undefined =>
  v === undefined || typeof v === 'string';

Prevention

Omit siteName entirely when it is optional; do not pass null.
Pass the name string from deploySite(), not the descriptor object.
Coerce config values: undefined stays undefined, everything else must be a string.

When it happens

Trigger: Passing a siteName that is null, a number, an object, or an array. Note undefined is allowed; the common mistake is passing null explicitly or a numeric/site identifier object.

Common situations: Reading siteName from config that yields null when absent; passing a deployment descriptor object instead of its name string; using 0 or a numeric id as the site name.

Related errors

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