{"record":{"id":"5e52ac0e176edc93","repo":"remotion-dev/remotion","slug":"the-bucketname-parameter-must-start-with-remotio","errorCode":null,"errorMessage":"The bucketName parameter must start with ${REMOTION_BUCKET_PREFIX}.","messagePattern":"The bucketName parameter must start with (.+?)\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cloudrun/src/shared/validate-bucketname.ts","lineNumber":22,"sourceCode":"import {randomHash} from './random-hash';\n\nexport const validateBucketName = (\n\tbucketName: unknown,\n\toptions: {\n\t\tmustStartWithRemotion: boolean;\n\t},\n) => {\n\tif (typeof bucketName !== 'string') {\n\t\tthrow new TypeError(\n\t\t\t`'bucketName' must be a string, but is ${JSON.stringify(bucketName)}`,\n\t\t);\n\t}\n\n\tif (\n\t\toptions.mustStartWithRemotion &&\n\t\t!bucketName.startsWith(REMOTION_BUCKET_PREFIX)\n\t) {\n\t\tthrow new Error(\n\t\t\t`The bucketName parameter must start with ${REMOTION_BUCKET_PREFIX}.`,\n\t\t);\n\t}\n\n\tif (\n\t\t!bucketName.match(\n\t\t\t/^(?=^.{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])$)/,\n\t\t)\n\t) {\n\t\tthrow new Error(`The bucket ${bucketName} `);\n\t}\n};\n\nexport const parseBucketName = (\n\tname: string,\n): {\n\tregion: GcpRegion | null;\n} => {","sourceCodeStart":4,"sourceCodeEnd":40,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/cloudrun/src/shared/validate-bucketname.ts#L4-L40","documentation":"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.","triggerScenarios":"Passing a bucket name without the 'remotioncloudrun-' prefix to an API that calls validateBucketName({ mustStartWithRemotion: true }) — typically bucket-creation or managed-bucket operations.","commonSituations":"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.","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."],"exampleFix":"// before\nawait deploySite({ bucketName: 'my-custom-bucket', ... });\n// after\nawait deploySite({ bucketName: 'remotioncloudrun-mybucket', ... });","handlingStrategy":"validation","validationCode":"import { REMOTION_BUCKET_PREFIX } from '@remotion/cloudrun/shared';\nif (!bucketName.startsWith(REMOTION_BUCKET_PREFIX)) {\n  bucketName = REMOTION_BUCKET_PREFIX + bucketName;\n}\nvalidateBucketName(bucketName, { mustStartWithRemotion: true });","typeGuard":"function hasRemotionPrefix(name: string): boolean {\n  return name.startsWith('remotioncloudrun-');\n}","tryCatchPattern":"// Pre-validate; only call the API once the prefix is correct.","preventionTips":["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."],"tags":["cloudrun","validation","bucket","naming"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}