google-gemini/gemini-cli · error · Error

Failed to create GCS bucket ${this.bucketName}: ${createErro

Error message

Failed to create GCS bucket ${this.bucketName}: ${createError}

What it means

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.

Source

Thrown at packages/a2a-server/src/persistence/gcs.ts:66

  }

  private async initializeBucket(): Promise<void> {
    try {
      const [buckets] = await this.storage.getBuckets();
      const exists = buckets.some((bucket) => bucket.name === this.bucketName);

      if (!exists) {
        logger.info(
          `Bucket ${this.bucketName} does not exist in the list. Attempting to create...`,
        );
        try {
          await this.storage.createBucket(this.bucketName);
          logger.info(`Bucket ${this.bucketName} created successfully.`);
        } catch (createError) {
          logger.info(
            `Failed to create bucket ${this.bucketName}: ${createError}`,
          );
          throw new Error(
            `Failed to create GCS bucket ${this.bucketName}: ${createError}`,
          );
        }
      } else {
        logger.info(`Bucket ${this.bucketName} exists.`);
      }
    } catch (error) {
      logger.info(
        `Error during bucket initialization for ${this.bucketName}: ${error}`,
      );
      throw new Error(
        `Failed to initialize GCS bucket ${this.bucketName}: ${error}`,
      );
    }
  }

  private async ensureBucketInitialized(): Promise<void> {
    await this.bucketInitialized;

View on GitHub (pinned to 5024443c72)

Solutions

1. Grant the service account storage.admin (or storage.buckets.create) on the project.
2. Pre-create the bucket manually (gsutil mb gs://name) so initializeBucket finds it in getBuckets.
3. Choose a globally unique, DNS-compliant bucket name (lowercase, 3-63 chars, hyphens not at start/end).
4. If 409, the bucket already exists under another project/owner - pick a different name.

Example fix

# before
export CODER_AGENT_GCS_BUCKET=My_Bucket
# createBucket fails: invalid name + permission

# after
gsutil mb -l US gs://my-agent-tasks-unique
export CODER_AGENT_GCS_BUCKET=my-agent-tasks-unique
gcloud projects add-iam-policy-binding $PROJECT --member=serviceAccount:$SA --role=roles/storage.admin

import { Storage } from '@google-cloud/storage';
async function canCreateBucket(bucket: string): Promise<boolean> {
  try { await new Storage().createBucket(bucket); return true; }
  catch { return false; }
}

try {
  store = new GCSTaskStore(bucket);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Failed to create GCS bucket')) {
    // pre-create externally, then retry on next boot
    throw new Error('Bucket auto-create failed; run gsutil mb gs://' + bucket + ' and grant storage.admin.');
  }
  throw e;
}

When it happens

Trigger: 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>'.

Common situations: 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).

Related errors

• Failed to initialize GCS bucket ${this.bucketName}: ${error}
• GCS bucket name is required.
• Task ${taskId} is missing persisted state in metadata.
• tar.c command failed to create ${tmpArchiveFile}
• Loaded metadata for task ${taskId} is missing internal persi

AI-assisted analysis of google-gemini/gemini-cli@5024443c72 (2026-08-12). Data as JSON: /api/errors/d1ace39d0ddac205. Report an issue: GitHub.