HumanSignal/label-studio · error · ValueError

When "FEATURE_FLAGS_FROM_FILE" is set, you have to specify a

Error message

When "FEATURE_FLAGS_FROM_FILE" is set, you have to specify a valid path for feature flags file, e.g.FEATURE_FLAGS_FILE=my_flags.yml

What it means

Label Studio raises this ValueError at startup when the FEATURE_FLAGS_FROM_FILE setting is truthy but FEATURE_FLAGS_FILE is empty or unset. The feature-flag loader needs a concrete file path to read flags from, and refuses to continue with a default. It is a fail-fast configuration sanity check in label_studio/core/feature_flags/base.py.

Source

Thrown at label_studio/core/feature_flags/base.py:34

logger = logging.getLogger(__name__)

get_user_repr = load_func(settings.FEATURE_FLAGS_GET_USER_REPR)
get_user_repr_from_organization = load_func(settings.FEATURE_FLAGS_GET_USER_REPR_FROM_ORGANIZATION)


def get_feature_file_path():
    package_name = 'label_studio' if settings.VERSION_EDITION == 'Community' else 'label_studio_enterprise'
    if settings.FEATURE_FLAGS_FILE.startswith('/'):
        return settings.FEATURE_FLAGS_FILE
    else:
        return find_node(package_name, settings.FEATURE_FLAGS_FILE, 'file')


if settings.FEATURE_FLAGS_FROM_FILE:
    # Feature flags from file
    if not settings.FEATURE_FLAGS_FILE:
        raise ValueError(
            'When "FEATURE_FLAGS_FROM_FILE" is set, you have to specify a valid path for feature flags file, e.g.'
            'FEATURE_FLAGS_FILE=my_flags.yml'
        )

    feature_flags_file = get_feature_file_path()

    logger.info(f'Read flags from file {feature_flags_file}')
    data_source = Files.new_data_source(paths=[feature_flags_file])
    config = Config(
        sdk_key=settings.FEATURE_FLAGS_API_KEY or 'whatever', update_processor_class=data_source, send_events=False
    )
    ldclient.set_config(config)
    client = ldclient.get()
elif settings.FEATURE_FLAGS_OFFLINE:
    # On-prem usage, without feature flags file
    ldclient.set_config(Config(settings.FEATURE_FLAGS_API_KEY or 'whatever', offline=True))
    client = ldclient.get()
else:

View on GitHub (pinned to 0b49e9b539)

Solutions

1. Set the FEATURE_FLAGS_FILE environment variable to a valid path to your flags file (e.g. FEATURE_FLAGS_FILE=my_flags.yml).
2. Ensure the file exists and is readable inside the container/pod (mount a volume or copy it into the image).
3. If you don't intend file-based flags, unset FEATURE_FLAGS_FROM_FILE (or set it to false/empty).
4. Verify the setting is picked up correctly — check for stray whitespace/typos in env config or values like '""' that look set but are empty.

Example fix

// before (docker-compose)
environment:
  - FEATURE_FLAGS_FROM_FILE=true
// after
environment:
  - FEATURE_FLAGS_FROM_FILE=true
  - FEATURE_FLAGS_FILE=/label_studio/my_flags.yml

import os
if os.environ.get('FEATURE_FLAGS_FROM_FILE', '').lower() in ('1','true','yes','on') and not os.environ.get('FEATURE_FLAGS_FILE'):
    raise SystemExit('FEATURE_FLAGS_FROM_FILE is set but FEATURE_FLAGS_FILE is missing')

def has_feature_flags_file() -> bool:
    return bool(getattr(settings, 'FEATURE_FLAGS_FILE', None))

try:
    from core.feature_flags import flags
except ValueError as e:
    logger.error('Feature flags misconfigured: %s', e)
    raise SystemExit(1)

When it happens

Trigger: Running Label Studio with env FEATURE_FLAGS_FROM_FILE set (truthy) while FEATURE_FLAGS_FILE is empty/unset; the check `if not settings.FEATURE_FLAGS_FILE` fires and ValueError is raised.

Common situations: Deployments enabling file-based feature flags (e.g. docker-compose with FEATURE_FLAGS_FROM_FILE=true) but forgetting to mount/copy the flags file or set FEATURE_FLAGS_FILE; renaming the env var or file without updating both settings; typos in the env var name.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Environment variable {key} must be an integer, got: {value}
• 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/f1657afb7702424e. Report an issue: GitHub.