HumanSignal/label-studio · error · NotImplementedError

validate_connection is not implemented

Error message

validate_connection is not implemented

What it means

BaseStorage (an abstract Django model) declares validate_connection as a required hook that concrete storage backends (S3, GCS, Azure, etc.) must implement to verify credentials/connectivity. The base implementation always raises NotImplementedError; hitting it means the method was called on a storage class that never overrode it.

Source

Thrown at label_studio/io_storages/base_models.py:318

                'and no traceback information is available.\n'
                'This typically occurs if job was manually removed '
                'or workers reloaded unexpectedly.'
            )
            self.save(update_fields=['status', 'traceback'])
            logger.info(f'Storage {self} status moved to `failed` because the job {self.last_sync_job} was not found')


class Storage(StorageInfo):
    url_scheme = ''

    title = models.CharField(_('title'), null=True, blank=True, max_length=256, help_text='Cloud storage title')
    description = models.TextField(_('description'), null=True, blank=True, help_text='Cloud storage description')
    created_at = models.DateTimeField(_('created at'), auto_now_add=True, help_text='Creation time')

    synchronizable = models.BooleanField(_('synchronizable'), default=True, help_text='If storage can be synced')

    def validate_connection(self, client=None):
        raise NotImplementedError('validate_connection is not implemented')

    class Meta:
        abstract = True


class ImportStorage(Storage):
    def iter_objects(self) -> Iterator[Any]:
        """
        Returns:
            Iterator[Any]: An iterator for objects in the storage.
        """
        raise NotImplementedError

    def iter_keys(self) -> Iterator[str]:
        """
        Returns:
            Iterator[str]: An iterator of keys for each object in the storage.
        """

View on GitHub (pinned to 0b49e9b539)

Solutions

1. Implement validate_connection in your storage subclass, using the client to perform a cheap read (e.g. list one bucket/container key) and raise on failure.
2. If using a built-in backend, ensure you are on a version where that backend implements validate_connection (upgrade Label Studio).
3. Avoid calling validate_connection on the abstract base directly; call it on the concrete storage model instance.

Example fix

// before
class MyStorage(ImportStorage):
    # no validate_connection override
    ...

// after
class MyStorage(ImportStorage):
    def validate_connection(self, client=None):
        try:
            client.list_buckets()
        except Exception as e:
            raise ValueError(f'Cannot connect to storage: {e}')

if type(storage).validate_connection is Storage.validate_connection:
    raise TypeError(f'{type(storage).__name__} must implement validate_connection()')

def implements_validate_connection(storage_cls) -> bool:
    return callable(getattr(storage_cls, 'validate_connection', None)) and \
           storage_cls.validate_connection.__qualname__ != Storage.validate_connection.__qualname__

try:
    storage.validate_connection(client)
except NotImplementedError:
    logger.warning('%s does not support connection validation; skipping', type(storage).__name__)
except ValueError as e:
    logger.error('Connection validation failed: %s', e)

When it happens

Trigger: Calling storage.validate_connection(...) on an instance of a custom or legacy storage subclass that does not override validate_connection; a custom backend added to Label Studio without implementing the connection-validation hook.

Common situations: Writing a custom ImportStorage/ExportStorage subclass and forgetting to implement validate_connection while the UI or API invokes it to test the connection; upgrades that newly call validate_connection on backends that predate it.

Related errors

• NotImplementedError
• You do not have permission to create storages for this proje
• Failed to list storage files
• "form_layout.yml" is not found for {self.__class__.__name__}
• Azure account name and key must be set using environment var

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