overleaf/overleaf · error · ReadError

failed to list objects in GCS

Error message

failed to list objects in GCS

What it means

Thrown by the private #listDirectory helper in GcsPersistor when bucket.getFiles({prefix}) fails (permission, missing bucket, or API fault). The raw error is wrapped into a ReadError with bucketName/prefix context; directorySize and files depend on this listing.

Source

Thrown at libraries/object-persistor/src/GcsPersistor.js:298

          { bucketName, key },
          WriteError
        )
        if (error instanceof NotFoundError) {
          return
        }
        throw error
      }
    } while (query)
  }

  async #listDirectory(bucketName, prefix) {
    try {
      const [response] = await this.storage
        .bucket(bucketName)
        .getFiles({ prefix })
      return response
    } catch (err) {
      throw PersistorHelper.wrapError(
        err,
        'failed to list objects in GCS',
        { bucketName, prefix },
        ReadError
      )
    }
  }

  async directorySize(bucketName, key) {
    const prefix = ensurePrefixIsDirectory(key)
    const files = await this.#listDirectory(bucketName, prefix)

    return files.reduce(
      (acc, file) => parseInt(file.metadata.size, 10) + acc,
      0
    )
  }

View on GitHub (pinned to 28ad3b03b7)

Solutions

1. Verify the bucket exists and the service account can list it
2. Check the prefix is well-formed for the directory layout
3. Inspect the wrapped cause for the GCS error
4. Retry transient GCS API failures with backoff

When it happens

Trigger: Thrown at libraries/object-persistor/src/GcsPersistor.js:298 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of overleaf/overleaf@28ad3b03b7 (2026-09-03). Data as JSON: /api/errors/95278b197e4fd201. Report an issue: GitHub.