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/lambda when the 'siteName' argument is provided (not undefined) but is not a string. siteName is used to namespace Remotion S3 buckets / serve artifacts; AWS bucket naming requires a string. undefined is allowed and means 'use default'.

Source

Thrown at packages/lambda/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

Pass a string siteName, or pass undefined / omit it to use the default.
Coerce before calling: typeof siteName === 'string' ? siteName : undefined.
If null should mean 'default', convert it: siteName: siteName ?? undefined.

Example fix

// before
await deploySite({ siteName: config.bucketSuffix }); // config.bucketSuffix is null

// after
await deploySite({ siteName: config.bucketSuffix ?? undefined });

Defensive patterns

Strategy: type-guard

Validate before calling

const siteName = typeof rawSiteName === 'string' && rawSiteName.length > 0 ? rawSiteName : undefined;

Type guard

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

Prevention

Type the field as string | undefined in your config schema.
Normalize null to undefined at the config boundary.
Run validateSiteName(value) in your own preflight to surface the error early.

When it happens

Trigger: Calling deploySite(), getOrCreateBucket(), or any API that takes siteName with a non-string value: a number, object, array, or boolean.

Common situations: Passing siteName from a loosely-typed config without coercion; spreading an object whose siteName field is null (null is not undefined and will trigger this) or 0.

Related errors

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