remotion-dev/remotion · error · TypeError

'bucketName' must be a string, but is ${JSON.stringify(bucke

Error message

'bucketName' must be a string, but is ${JSON.stringify(bucketName)}

What it means

Thrown by validateBucketName() when bucketName is not a string (e.g., undefined, null, number, object). This is the type guard that runs before any GCS bucket string validation. It exists because the public API accepts bucketName from user config where TypeScript cannot enforce runtime types.

Source

Thrown at packages/cloudrun/src/shared/validate-bucketname.ts:13

import type {GcpRegion} from '../pricing/gcp-regions';
import {GCP_REGIONS} from '../regions';
import {REMOTION_BUCKET_PREFIX} from './constants';
import {randomHash} from './random-hash';

export const validateBucketName = (
	bucketName: unknown,
	options: {
		mustStartWithRemotion: boolean;
	},
) => {
	if (typeof bucketName !== 'string') {
		throw new TypeError(
			`'bucketName' must be a string, but is ${JSON.stringify(bucketName)}`,
		);
	}

	if (
		options.mustStartWithRemotion &&
		!bucketName.startsWith(REMOTION_BUCKET_PREFIX)
	) {
		throw new Error(
			`The bucketName parameter must start with ${REMOTION_BUCKET_PREFIX}.`,
		);
	}

	if (
		!bucketName.match(
			/^(?=^.{3,63}$)(?!^(\d+\.)+\d+$)(^(([a-z0-9]|[a-z0-9][a-z0-9-]*[a-z0-9])\.)*([a-z0-9]|[a-z0-9][a-z0-9-]*[a-z0-9])$)/,
		)
	) {

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Ensure bucketName is a string before calling the API; default it from env with a guard.
2. Check the source of the value (env var, config file) and fix the unset/missing assignment.
3. Pass a literal bucket name string during local testing.

Example fix

// before
const { BUCKET } = process.env; // undefined when unset
await deploySite({ bucketName: BUCKET, ... });
// after
const bucketName = process.env.BUCKET;
if (typeof bucketName !== 'string') throw new Error('BUCKET env var is not set');
await deploySite({ bucketName, ... });

import { validateBucketName } from '@remotion/cloudrun/shared';
validateBucketName(bucketName, { mustStartWithRemotion: true });

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

if (typeof bucketName !== 'string') throw new Error('bucketName must be a string');
// proceed only after guard

When it happens

Trigger: Calling any @remotion/cloudrun API that takes a bucket name with a non-string value: undefined, null, a number, or an object. Triggered before the prefix or regex checks.

Common situations: Reading bucketName from an env var that is unset (becomes undefined); passing a config object instead of its string property; a typo in destructuring leaving the value undefined.

Related errors

• The bucketName parameter must start with ${REMOTION_BUCKET_P
• The bucket ${bucketName}
• "cloudRunUrl" parameter must be a string, but is ${JSON.stri
• "codec" must be a string
• Privacy must be a string

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