{"record":{"id":"aca30af275302b53","repo":"remotion-dev/remotion","slug":"bucketname-must-be-a-string-but-is-json-strin","errorCode":null,"errorMessage":"'bucketName' must be a string, but is ${JSON.stringify(bucketName)}","messagePattern":"'bucketName' must be a string, but is (.+?)","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"packages/cloudrun/src/shared/validate-bucketname.ts","lineNumber":13,"sourceCode":"import type {GcpRegion} from '../pricing/gcp-regions';\nimport {GCP_REGIONS} from '../regions';\nimport {REMOTION_BUCKET_PREFIX} from './constants';\nimport {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) {","sourceCodeStart":1,"sourceCodeEnd":31,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/cloudrun/src/shared/validate-bucketname.ts#L1-L31","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure bucketName is a string before calling the API; default it from env with a guard.","Check the source of the value (env var, config file) and fix the unset/missing assignment.","Pass a literal bucket name string during local testing."],"exampleFix":"// before\nconst { BUCKET } = process.env; // undefined when unset\nawait deploySite({ bucketName: BUCKET, ... });\n// after\nconst bucketName = process.env.BUCKET;\nif (typeof bucketName !== 'string') throw new Error('BUCKET env var is not set');\nawait deploySite({ bucketName, ... });","handlingStrategy":"type-guard","validationCode":"import { validateBucketName } from '@remotion/cloudrun/shared';\nvalidateBucketName(bucketName, { mustStartWithRemotion: true });","typeGuard":"function isBucketNameString(v: unknown): v is string {\n  return typeof v === 'string';\n}","tryCatchPattern":"if (typeof bucketName !== 'string') throw new Error('bucketName must be a string');\n// proceed only after guard","preventionTips":["Assert env-backed values are strings at startup.","Type config objects strictly so missing fields surface as compile errors.","Default bucketName from a known constant when env is unset."],"tags":["cloudrun","validation","typescript","bucket"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}