remotion-dev/remotion · error · Error

The bucketName parameter must start with ${REMOTION_BUCKET_P

Error message

The bucketName parameter must start with ${REMOTION_BUCKET_PREFIX}.

What it means

Thrown by validateBucketName() when options.mustStartWithRemotion is true and bucketName does not start with the 'remotioncloudrun-' prefix. Cloud Run buckets managed by Remotion must use this prefix so the CLI can discover and operate on them consistently. Non-prefixed names are rejected only when the caller opts into the mustStartWithRemotion constraint.

Source

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

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])$)/,
		)
	) {
		throw new Error(`The bucket ${bucketName} `);
	}
};

export const parseBucketName = (
	name: string,
): {
	region: GcpRegion | null;
} => {

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Prefix your bucket name with 'remotioncloudrun-', e.g. 'remotioncloudrun-mybucket'.
Use `npx remotion cloudrun buckets create` to let Remotion generate a correctly-named bucket.
If you must use an existing custom bucket, only do so for APIs that pass mustStartWithRemotion: false.

Example fix

// before
await deploySite({ bucketName: 'my-custom-bucket', ... });
// after
await deploySite({ bucketName: 'remotioncloudrun-mybucket', ... });

Defensive patterns

Strategy: validation

Validate before calling

import { REMOTION_BUCKET_PREFIX } from '@remotion/cloudrun/shared';
if (!bucketName.startsWith(REMOTION_BUCKET_PREFIX)) {
  bucketName = REMOTION_BUCKET_PREFIX + bucketName;
}
validateBucketName(bucketName, { mustStartWithRemotion: true });

Type guard

function hasRemotionPrefix(name: string): boolean {
  return name.startsWith('remotioncloudrun-');
}

Try / catch

// Pre-validate; only call the API once the prefix is correct.

Prevention

Generate buckets with `npx remotion cloudrun buckets create` so the prefix is automatic.
Use the REMOTION_BUCKET_PREFIX constant rather than hardcoding the string.
Document the prefix requirement anywhere bucket names are configured.

When it happens

Trigger: Passing a bucket name without the 'remotioncloudrun-' prefix to an API that calls validateBucketName({ mustStartWithRemotion: true }) — typically bucket-creation or managed-bucket operations.

Common situations: Passing a pre-existing GCS bucket with a custom name to a Remotion-managed flow; assuming any bucket name is accepted; name generated by a different tool.

Related errors

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