google-gemini/gemini-cli · error · Error

GCS bucket name is required.

Error message

GCS bucket name is required.

What it means

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.

Source

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

const getTmpArchiveFilename = (taskId: string): string =>
  `task-${taskId}-workspace-${uuidv4()}.tar.gz`;

// Validate the taskId to prevent path traversal attacks by ensuring it only contains safe characters.
const isTaskIdValid = (taskId: string): boolean => {
  // Allow only alphanumeric characters, dashes, and underscores, and ensure it's not empty.
  const validTaskIdRegex = /^[a-zA-Z0-9_-]+$/;
  return validTaskIdRegex.test(taskId);
};

export class GCSTaskStore implements TaskStore {
  private storage: Storage;
  private bucketName: string;
  private bucketInitialized: Promise<void>;

  constructor(bucketName: string) {
    if (!bucketName) {
      throw new Error('GCS bucket name is required.');
    }
    this.storage = new Storage();
    this.bucketName = bucketName;
    logger.info(`GCSTaskStore initializing with bucket: ${this.bucketName}`);
    // Prerequisites: user account or service account must have storage admin IAM role
    // and the bucket name must be unique.
    this.bucketInitialized = this.initializeBucket();
  }

  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...`,
        );

View on GitHub (pinned to 5024443c72)

Solutions

1. Provide a non-empty bucket name when constructing GCSTaskStore (read from a validated env var).
2. Validate the env var at startup and fail with a clear message before reaching the constructor.
3. If GCS persistence is optional, only construct GCSTaskStore when the bucket is configured; otherwise use an in-memory/no-op store.

Example fix

// before
const store = new GCSTaskStore(process.env['CODER_AGENT_GCS_BUCKET']);
// throws if env var unset

// after
const bucket = process.env['CODER_AGENT_GCS_BUCKET'];
if (!bucket) throw new Error('CODER_AGENT_GCS_BUCKET must be set for GCS persistence');
const store = new GCSTaskStore(bucket);

const bucket = process.env['CODER_AGENT_GCS_BUCKET'];
if (!bucket) throw new Error('CODER_AGENT_GCS_BUCKET must be set to use GCSTaskStore.');
const store = new GCSTaskStore(bucket);

function isNonEmptyString(v: unknown): v is string {
  return typeof v === 'string' && v.length > 0;
}

When it happens

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

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

Related errors

• [${logPrefix}] Unable to set GeneratorConfig. Please provide
• Failed to create GCS bucket ${this.bucketName}: ${createErro
• Failed to initialize GCS bucket ${this.bucketName}: ${error}
• Task ${taskId} is missing persisted state in metadata.
• tar.c command failed to create ${tmpArchiveFile}

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