{"record":{"id":"db93236ea39745dd","repo":"google-gemini/gemini-cli","slug":"gcs-bucket-name-is-required","errorCode":null,"errorMessage":"GCS bucket name is required.","messagePattern":"GCS bucket name is required\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/a2a-server/src/persistence/gcs.ts","lineNumber":40,"sourceCode":"\nconst getTmpArchiveFilename = (taskId: string): string =>\n  `task-${taskId}-workspace-${uuidv4()}.tar.gz`;\n\n// Validate the taskId to prevent path traversal attacks by ensuring it only contains safe characters.\nconst isTaskIdValid = (taskId: string): boolean => {\n  // Allow only alphanumeric characters, dashes, and underscores, and ensure it's not empty.\n  const validTaskIdRegex = /^[a-zA-Z0-9_-]+$/;\n  return validTaskIdRegex.test(taskId);\n};\n\nexport class GCSTaskStore implements TaskStore {\n  private storage: Storage;\n  private bucketName: string;\n  private bucketInitialized: Promise<void>;\n\n  constructor(bucketName: string) {\n    if (!bucketName) {\n      throw new Error('GCS bucket name is required.');\n    }\n    this.storage = new Storage();\n    this.bucketName = bucketName;\n    logger.info(`GCSTaskStore initializing with bucket: ${this.bucketName}`);\n    // Prerequisites: user account or service account must have storage admin IAM role\n    // and the bucket name must be unique.\n    this.bucketInitialized = this.initializeBucket();\n  }\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        );","sourceCodeStart":22,"sourceCodeEnd":58,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/packages/a2a-server/src/persistence/gcs.ts#L22-L58","documentation":"Thrown by the GCSTaskStore constructor when bucketName is falsy (empty string, null, undefined). The store cannot operate without a target bucket, so it fails fast during construction. Note this is synchronous: the constructor runs initializeBucket() eagerly and stores the promise, but the bucketName check happens before any I/O.","triggerScenarios":"Instantiating `new GCSTaskStore(bucketName)` with an empty/undefined value - typically the result of reading an unset env var like process.env['CODER_AGENT_GCS_BUCKET'] || '' and passing it through.","commonSituations":"Persisting tasks to GCS without configuring the bucket env var; typo in the env var name; default config path that doesn't set a bucket for non-GCS deployments.","solutions":["Provide a non-empty bucket name when constructing GCSTaskStore (read from a validated env var).","Validate the env var at startup and fail with a clear message before reaching the constructor.","If GCS persistence is optional, only construct GCSTaskStore when the bucket is configured; otherwise use an in-memory/no-op store."],"exampleFix":"// before\nconst store = new GCSTaskStore(process.env['CODER_AGENT_GCS_BUCKET']);\n// throws if env var unset\n\n// after\nconst bucket = process.env['CODER_AGENT_GCS_BUCKET'];\nif (!bucket) throw new Error('CODER_AGENT_GCS_BUCKET must be set for GCS persistence');\nconst store = new GCSTaskStore(bucket);","handlingStrategy":"validation","validationCode":"const bucket = process.env['CODER_AGENT_GCS_BUCKET'];\nif (!bucket) throw new Error('CODER_AGENT_GCS_BUCKET must be set to use GCSTaskStore.');\nconst store = new GCSTaskStore(bucket);","typeGuard":"function isNonEmptyString(v: unknown): v is string {\n  return typeof v === 'string' && v.length > 0;\n}","tryCatchPattern":null,"preventionTips":["Validate the bucket env var at startup, before constructing GCSTaskStore.","If GCS is optional, only construct the store when the bucket is configured.","Use a typed config loader that fails fast on missing required fields.","Add a config schema test that catches missing-bucket regressions."],"tags":["gcs","persistence","config","constructor","env-vars"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}