HumanSignal/label-studio · error · ValueError

Environment variable {key} must be an integer, got: {value}

Error message

Environment variable {key} must be an integer, got: {value}

What it means

get_int_env reads an environment variable via get_env and coerces it to int. If the variable is set but its value cannot be parsed by int(), it raises ValueError with this message. This fails fast at startup for misconfigured integer environment settings.

Source

Thrown at label_studio/core/utils/params.py:137

                return bool_from_request(os.environ, env_key, default)
            else:
                return value
    return default


def has_env(name: str) -> bool:
    """Return True if any supported environment variable name is set for ``name``."""
    return any((prefix + name) in os.environ for prefix in ('LABEL_STUDIO_', 'HEARTEX_', ''))


def get_int_env(key, default=None):
    value = get_env(key)
    if value is None:
        return default
    try:
        return int(value)
    except ValueError:
        raise ValueError(f'Environment variable {key} must be an integer, got: {value}')


def get_bool_env(key, default):
    return get_env(key, default, is_bool=True)


T = TypeVar('T')


def get_env_list(
    key: str, default: Optional[Sequence[T]] = None, value_transform: Callable[[str], T] = str
) -> Sequence[T]:
    """
    "foo,bar,baz" in env variable => ["foo", "bar", "baz"] in python.
    Use value_transform to convert the strings to any other type.
    """
    value = get_env(key)
    if not value:

View on GitHub (pinned to 0b49e9b539)

Solutions

1. Fix the environment variable to a plain integer string, e.g. LABEL_STUDIO_SOME_LIMIT=300.
2. Remove units and decimals: '300s' → '300', '10.5' → '10'.
3. Check .env/secret managers for stray quotes or trailing spaces in the value.
4. Unset the variable so the documented default applies if you did not intend to override it.

Example fix

// before (docker-compose.yml)
- LABEL_STUDIO_TASK_FETCH_POOL_SIZE=10x

// after
- LABEL_STUDIO_TASK_FETCH_POOL_SIZE=10

import os
def ensure_int_env(key):
    value = os.environ.get(key)
    if value is not None:
        int(value)  # raises ValueError early with a clear message

def is_int_str(value) -> bool:
    try:
        int(value)
        return True
    except (TypeError, ValueError):
        return False

try:
    pool_size = get_int_env('LABEL_STUDIO_TASK_FETCH_POOL_SIZE', 10)
except ValueError as e:
    logging.error('Bad env config: %s', e)
    raise SystemExit(1)

When it happens

Trigger: Setting an env var consumed by get_int_env (e.g. LABEL_STUDIO_* integer settings) to a non-integer string like 'abc', '10s', or '10.5'.

Common situations: Docker/Kubernetes compose files with typo'd values; durations written with units ('300s'); decimals where ints are required; stray quotes or whitespace in .env files that survive parsing.

Related errors

• When "FEATURE_FLAGS_FROM_FILE" is set, you have to specify a
• SECURE_PROXY_SSL_HEADER must be configured as "<header>,<val
• Azure account name and key must be set using environment var
• LABEL_STUDIO_HOST must be a subpath if DOMAIN_FROM_REQUEST i
• User filter list exceeds maximum size of {settings.DATA_MANA

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