HumanSignal/label-studio · error · ValueError

Please explicitly pass a redis db id to prevent accidentally

Error message

Please explicitly pass a redis db id to prevent accidentally overwriting existing database!

What it means

get_redis_connection() in label_studio/io_storages/redis/models.py deliberately refuses to connect when no Redis database number (`db`) is supplied. Redis defaults to db 0, and Label Studio could silently overwrite tasks stored there by another app, so the guard forces you to choose the db explicitly. It is a fail-fast ValueError raised before any network I/O.

Source

Thrown at label_studio/io_storages/redis/models.py:57

    )

    def get_redis_connection(self, db=None, redis_config={}):
        """Get a redis connection from the provided arguments.

        Args:
            db (int): Database ID of database to use. This needs to
                      always be provided to prevent accidental overwrite
                      to a default value. Therefore, the default is None,
                      but raises an error if not provided.
            redis_config (dict, optional): Further redis configuration.

        Returns:
            redis.StrictRedis object with connection to database.
        """
        if not db:
            # This should never happen, but better to check than to accidentally
            # overwrite an existing database by choosing a wrong default:
            raise ValueError(
                'Please explicitly pass a redis db id to prevent accidentally overwriting existing database!'
            )

        # Since tasks are always text, we use StrictRedis with utf-8 decoding.
        r = redis.StrictRedis(db=db, charset='utf-8', decode_responses=True, **redis_config)
        # Test connection
        # (this will raise redis.exceptions.ConnectionError if it cannot connect)
        r.ping()
        return r

    def get_client(self):
        redis_config = {}
        if self.host:
            redis_config['host'] = self.host
        if self.port:
            redis_config['port'] = self.port
        if self.password:
            redis_config['password'] = self.password

View on GitHub (pinned to 0b49e9b539)

Solutions

Pass an explicit db argument, e.g. get_redis_connection(db=1, redis_config={...}).
When using the API/serializer, include the `db` field in the storage creation payload.
If db comes from an env var, ensure REDIS_DB (or equivalent) is set and non-empty before constructing the storage.

Example fix

// before
r = get_redis_connection(redis_config={'host': 'localhost', 'port': 6379})

// after
r = get_redis_connection(db=1, redis_config={'host': 'localhost', 'port': 6379})

Defensive patterns

Strategy: validation

Validate before calling

def ensure_redis_db(config: dict) -> int:
    db = config.get('db') or int(os.environ.get('REDIS_DB', 0))
    if not db:
        raise ValueError('Set an explicit Redis db (e.g. REDIS_DB=1) before connecting.')
    return db

# call before storage creation
db = ensure_redis_db(storage_config)

Type guard

def has_redis_db(cfg: dict) -> bool:
    db = cfg.get('db')
    return isinstance(db, int) and db > 0

Prevention

Always set REDIS_DB (non-zero) in deployment env vars.
Never call get_redis_connection without an explicit db kwarg.
Use the RedisImportStorageSerializer so `db` is enforced at the API boundary.
Keep a dedicated db number per application sharing the Redis instance.

When it happens

Trigger: Calling get_redis_connection(db=None) (or falsy db such as 0) with only host/port/password in redis_config — e.g. constructing RedisImportStorage without the `db` field, or passing db via a template that renders empty.

Common situations: Setting only REDIS_HOST/REDIS_PORT env vars and forgetting REDIS_DB; programmatically instantiating RedisImportStorage(**data) where the serializer was never used so `db` was never required; copying a redis:// URL into config but not extracting the db number.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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