{"record":{"id":"9c33ef3511395347","repo":"google-gemini/gemini-cli","slug":"failed-to-initialize-gcs-bucket-this-bucketname","errorCode":null,"errorMessage":"Failed to initialize GCS bucket ${this.bucketName}: ${error}","messagePattern":"Failed to initialize GCS bucket (.+?): (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/a2a-server/src/persistence/gcs.ts","lineNumber":77,"sourceCode":"        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;\n  }\n\n  private getObjectPath(taskId: string, type: ObjectType): string {\n    if (!isTaskIdValid(taskId)) {\n      throw new Error(`Invalid taskId: ${taskId}`);\n    }\n    return `tasks/${taskId}/${type}.tar.gz`;\n  }\n\n  async save(task: SDKTask): Promise<void> {\n    await this.ensureBucketInitialized();","sourceCodeStart":59,"sourceCodeEnd":95,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/packages/a2a-server/src/persistence/gcs.ts#L59-L95","documentation":"Thrown by the outer catch of GCSTaskStore.initializeBucket, wrapping any error from getBuckets() or rethrown errors that escape the inner createBucket handler. This is the generic bucket-init failure: listing buckets failed (auth, network, permission), or an unexpected error type slipped past the inner catch. Because initialization is stored as a promise and awaited via ensureBucketInitialized, this error surfaces later on the first save/load call.","triggerScenarios":"getBuckets() rejects (no auth, no network, project not set); a non-Error thrown inside the init path; the inner createBucket error type isn't caught because it was already wrapped. The promise stored in this.bucketInitialized rejects, and the next ensureBucketInitialized() await rethrows.","commonSituations":"Service account has no storage.buckets.list permission; GOOGLE_CLOUD_PROJECT / project ID not inferred; running outside GCP with no credentials at all; transient network failure during boot.","solutions":["Inspect the interpolated error string - it names the underlying cause (permission denied, network, no project).","Ensure Application Default Credentials are available (GOOGLE_APPLICATION_CREDENTIALS or GCE metadata).","Grant storage.buckets.list / storage.buckets.get so getBuckets succeeds.","Because the failed promise is cached, restart the process after fixing credentials - ensureBucketInitialized will keep rethrowing the cached rejection."],"exampleFix":"# before\nexport CODER_AGENT_GCS_BUCKET=my-agent-tasks\n# no ADC -> getBuckets rejects -> 'Failed to initialize GCS bucket'\n\n# after\nexport GOOGLE_APPLICATION_CREDENTIALS=/secrets/sa.json\ngcloud auth activate-service-account --key-file=/secrets/sa.json\n# restart the agent process so initializeBucket re-runs","handlingStrategy":"try-catch","validationCode":"import { Storage } from '@google-cloud/storage';\nasync function gcsReachable(bucket: string): Promise<boolean> {\n  try { await new Storage().getBuckets(); return true; } catch { return false; }\n}","typeGuard":null,"tryCatchPattern":"try {\n  await store.save(task);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Failed to initialize GCS bucket')) {\n    // restart needed - the cached init promise rejected\n    process.exit(1);\n  }\n  throw e;\n}","preventionTips":["Confirm Application Default Credentials resolve (gcloud auth application-default login or GOOGLE_APPLICATION_CREDENTIALS).","Grant storage.buckets.list so getBuckets succeeds during init.","Restart the process after fixing credentials - the rejected bucketInitialized promise is cached for the process lifetime.","Run a connectivity smoke test in your health check."],"tags":["gcs","persistence","iam","initialization","auth"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}