{"record":{"id":"d1ace39d0ddac205","repo":"google-gemini/gemini-cli","slug":"failed-to-create-gcs-bucket-this-bucketname","errorCode":null,"errorMessage":"Failed to create GCS bucket ${this.bucketName}: ${createError}","messagePattern":"Failed to create GCS bucket (.+?): (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/a2a-server/src/persistence/gcs.ts","lineNumber":66,"sourceCode":"  }\n\n  private async initializeBucket(): Promise<void> {\n    try {\n      const [buckets] = await this.storage.getBuckets();\n      const exists = buckets.some((bucket) => bucket.name === this.bucketName);\n\n      if (!exists) {\n        logger.info(\n          `Bucket ${this.bucketName} does not exist in the list. Attempting to create...`,\n        );\n        try {\n          await this.storage.createBucket(this.bucketName);\n          logger.info(`Bucket ${this.bucketName} created successfully.`);\n        } catch (createError) {\n          logger.info(\n            `Failed to create bucket ${this.bucketName}: ${createError}`,\n          );\n          throw new Error(\n            `Failed to create GCS bucket ${this.bucketName}: ${createError}`,\n          );\n        }\n      } else {\n        logger.info(`Bucket ${this.bucketName} exists.`);\n      }\n    } catch (error) {\n      logger.info(\n        `Error during bucket initialization for ${this.bucketName}: ${error}`,\n      );\n      throw new Error(\n        `Failed to initialize GCS bucket ${this.bucketName}: ${error}`,\n      );\n    }\n  }\n\n  private async ensureBucketInitialized(): Promise<void> {\n    await this.bucketInitialized;","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/packages/a2a-server/src/persistence/gcs.ts#L48-L84","documentation":"Thrown by GCSTaskStore.initializeBucket when storage.createBucket(bucketName) fails after confirming the bucket doesn't exist in getBuckets. The inner catch wraps the createBucket error into a readable message. Common causes: the name is already globally taken (GCS bucket names share a single namespace), the name violates naming rules, or the authenticated account lacks storage.buckets.create IAM permission.","triggerScenarios":"Constructor fires initializeBucket; getBuckets returns a list not containing the name; createBucket rejects with a GoogleCloudStorage error (409 BucketAlreadyOwnedByYou/already exists race, 403 forbidden, 400 invalid name). The inner catch rewrites it as 'Failed to create GCS bucket <name>: <err>'.","commonSituations":"First run in a project where the bucket doesn't exist and the service account lacks storage.admin; bucket name collides with another GCP project's bucket; name contains uppercase or underscores (GCS requires lowercase/digits/hyphens).","solutions":["Grant the service account storage.admin (or storage.buckets.create) on the project.","Pre-create the bucket manually (gsutil mb gs://name) so initializeBucket finds it in getBuckets.","Choose a globally unique, DNS-compliant bucket name (lowercase, 3-63 chars, hyphens not at start/end).","If 409, the bucket already exists under another project/owner - pick a different name."],"exampleFix":"# before\nexport CODER_AGENT_GCS_BUCKET=My_Bucket\n# createBucket fails: invalid name + permission\n\n# after\ngsutil mb -l US gs://my-agent-tasks-unique\nexport CODER_AGENT_GCS_BUCKET=my-agent-tasks-unique\ngcloud projects add-iam-policy-binding $PROJECT --member=serviceAccount:$SA --role=roles/storage.admin","handlingStrategy":"try-catch","validationCode":"import { Storage } from '@google-cloud/storage';\nasync function canCreateBucket(bucket: string): Promise<boolean> {\n  try { await new Storage().createBucket(bucket); return true; }\n  catch { return false; }\n}","typeGuard":null,"tryCatchPattern":"try {\n  store = new GCSTaskStore(bucket);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Failed to create GCS bucket')) {\n    // pre-create externally, then retry on next boot\n    throw new Error('Bucket auto-create failed; run gsutil mb gs://' + bucket + ' and grant storage.admin.');\n  }\n  throw e;\n}","preventionTips":["Pre-create the bucket with gsutil/terraform so initializeBucket finds it in getBuckets.","Grant the service account storage.admin on the project.","Choose a globally unique, DNS-compliant name (lowercase, 3-63 chars).","Treat bucket creation as infra, not runtime - separate provisioning from app startup."],"tags":["gcs","persistence","iam","bucket-creation","startup"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}