google-gemini/gemini-cli · error · Error

Failed to initialize GCS bucket ${this.bucketName}: ${error}

Error message

Failed to initialize GCS bucket ${this.bucketName}: ${error}

What it means

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.

Source

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

        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;
  }

  private getObjectPath(taskId: string, type: ObjectType): string {
    if (!isTaskIdValid(taskId)) {
      throw new Error(`Invalid taskId: ${taskId}`);
    }
    return `tasks/${taskId}/${type}.tar.gz`;
  }

  async save(task: SDKTask): Promise<void> {
    await this.ensureBucketInitialized();

View on GitHub (pinned to 5024443c72)

Solutions

1. Inspect the interpolated error string - it names the underlying cause (permission denied, network, no project).
2. Ensure Application Default Credentials are available (GOOGLE_APPLICATION_CREDENTIALS or GCE metadata).
3. Grant storage.buckets.list / storage.buckets.get so getBuckets succeeds.
4. Because the failed promise is cached, restart the process after fixing credentials - ensureBucketInitialized will keep rethrowing the cached rejection.

Example fix

# before
export CODER_AGENT_GCS_BUCKET=my-agent-tasks
# no ADC -> getBuckets rejects -> 'Failed to initialize GCS bucket'

# after
export GOOGLE_APPLICATION_CREDENTIALS=/secrets/sa.json
gcloud auth activate-service-account --key-file=/secrets/sa.json
# restart the agent process so initializeBucket re-runs

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

try {
  await store.save(task);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Failed to initialize GCS bucket')) {
    // restart needed - the cached init promise rejected
    process.exit(1);
  }
  throw e;
}

When it happens

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

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

Related errors

• Failed to create GCS bucket ${this.bucketName}: ${createErro
• 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/9c33ef3511395347. Report an issue: GitHub.