HumanSignal/label-studio · error · ValueError

No blobs found in {bucket_name}/{prefix} or prefix doesn't e

Error message

No blobs found in {bucket_name}/{prefix} or prefix doesn't exist

What it means

Label Studio's GCS storage raises this ValueError during connection validation when the configured bucket+prefix yields no blobs. GCS itself has no real folders, so an empty result usually means the prefix is misspelled, the bucket is empty, or the credentials lack list permission (which surfaces as an empty list here rather than an error). It is thrown by GCS.validate_connection, which is invoked when a GCS import/export storage is created or tested via the API.

Source

Thrown at label_studio/io_storages/gcs/utils.py:105

        prefix: str = None,
        use_glob_syntax: bool = False,
    ):
        logger.debug('Validating GCS connection')
        client = cls.get_client(
            google_application_credentials=google_application_credentials, google_project_id=google_project_id
        )
        logger.debug('Validating GCS bucket')
        bucket = client.get_bucket(bucket_name)

        # Dataset storages uses glob syntax and we want to add explicit checks
        # In the future when GCS lib supports it
        if use_glob_syntax:
            pass
        else:
            if prefix:
                blobs = list(bucket.list_blobs(prefix=prefix, max_results=1))
                if not blobs:
                    raise ValueError(f"No blobs found in {bucket_name}/{prefix} or prefix doesn't exist")

    @classmethod
    def iter_blobs(
        cls,
        client: gcs.Client,
        bucket_name: str,
        prefix: str = None,
        regex_filter: str = None,
        limit: int = None,
        return_key: bool = False,
        recursive_scan: bool = True,
    ):
        """
        Iterate files on the bucket. Optionally return limited number of files that match provided extensions
        :param client: GCS Client obj
        :param bucket_name: bucket name
        :param prefix: bucket prefix
        :param regex_filter: RegEx filter

View on GitHub (pinned to 0b49e9b539)

Solutions

1. Verify the exact object key prefix in the GCP console (gsutil ls gs://<bucket>/<prefix>) and correct the storage prefix, removing any leading slash
2. Check that use_glob_syntax matches your intent: globs are only honored when it is True; a literal '*' in the prefix will match nothing
3. Confirm the service account has storage.objects.list (roles/storage.objectViewer) on the bucket
4. Verify GOOGLE_APPLICATION_CREDENTIALS / google_project_id point to the project that actually contains the bucket

Example fix

// before
storage = GCSImportStorage(bucket='my-bucket', prefix='/dataset/tasks/')  # leading slash matches nothing
// after
storage = GCSImportStorage(bucket='my-bucket', prefix='dataset/tasks/')

from google.cloud import storage
client = storage.Client()
blobs = client.list_blobs(bucket_name, prefix=prefix.strip('/'), max_results=1)
if not any(blobs):
    raise SystemExit(f"Prefix gs://{bucket_name}/{prefix} has no objects — fix prefix or check IAM")

def prefix_has_objects(bucket_name: str, prefix: str) -> bool:
    if not prefix or prefix.startswith('/'):
        return False
    it = client.list_blobs(bucket_name, prefix=prefix, max_results=1)
    try:
        next(iter(it))
        return True
    except StopIteration:
        return False

try:
    storage.validate_connection()
except ValueError as e:
    if 'No blobs found' in str(e):
        logger.warning('GCS prefix empty/missing: %s', e)
    else:
        raise

When it happens

Trigger: Calling validate/validate_connection on a GCSImportStorage/GCSExportStorage with (a) a prefix that matches no objects, (b) a prefix for a 'folder' that was never created (GCS folders are virtual), or (c) use_glob_syntax=False and a bucket where list_blobs(prefix=..., max_results=1) returns nothing (including permission-denied silently hiding objects in some setups).

Common situations: Typos in the storage prefix ('/data/tasks' vs 'data/tasks'); leading slash added by a UI copy-paste; syncing to a bucket region/project mismatch; service account without storage.objects.list; expecting glob patterns to work while use_glob_syntax is False.

Related errors

• User filter list exceeds maximum size of {settings.DATA_MANA
• "form_layout.yml" is not found for {self.__class__.__name__}
• Azure account name and key must be set using environment var
• Azure account name and key must be set using environment var
• Invalid or missing serializer class

AI-assisted analysis of HumanSignal/label-studio@0b49e9b539 (2026-08-29). Data as JSON: /api/errors/2a8c89f3ff29e6b5. Report an issue: GitHub.