HumanSignal/label-studio · error · ValidationError

Serving local files from the host filesystem can be a securi

Error message

Serving local files from the host filesystem can be a security risk, so LOCAL_FILES_SERVING_ENABLED is disabled by default. To enable Local Files storage, set the LOCAL_FILES_SERVING_ENABLED environment variable to "true" and restart Label Studio. See https://labelstud.io/guide/storage.html#Local-storage for details.\n\n{self.community_auto_hint()}

What it means

Serving files from the host filesystem is disabled by default in Label Studio for security reasons. validate_connection raises this Django ValidationError when LOCAL_FILES_SERVING_ENABLED is explicitly False. It is an explicit opt-in guard: the storage configuration may be perfectly valid, but local file serving must be turned on via environment variable before the storage can be used.

Source

Thrown at label_studio/io_storages/localfiles/models.py:100

        document_root = Path(settings.LOCAL_FILES_DOCUMENT_ROOT)
        example_path = Path(settings.LOCAL_FILES_DOCUMENT_ROOT) / 'dataset1'

        if not path.exists():
            raise ValidationError(f'Absolute local path "{self.path}" does not exist')
        if document_root == path:
            raise ValidationError(
                f'Absolute local path "{self.path}" cannot be the same as '
                f'LOCAL_FILES_DOCUMENT_ROOT="{settings.LOCAL_FILES_DOCUMENT_ROOT}" by security reasons. Please add a subdirectory. '
                f'For example: "{example_path}".'
            )
        if document_root not in path.parents:
            raise ValidationError(
                f'Absolute local path "{self.path}" must be a subdirectory of '
                f'LOCAL_FILES_DOCUMENT_ROOT="{settings.LOCAL_FILES_DOCUMENT_ROOT}" by security reasons. '
                f'For example: "{example_path}".'
            )
        if settings.LOCAL_FILES_SERVING_ENABLED is False:
            raise ValidationError(
                'Serving local files from the host filesystem can be a security risk, so '
                'LOCAL_FILES_SERVING_ENABLED is disabled by default. '
                'To enable Local Files storage, set the LOCAL_FILES_SERVING_ENABLED environment '
                'variable to "true" and restart Label Studio. See '
                'https://labelstud.io/guide/storage.html#Local-storage for details.'
                '\n\n'
                f'{self.community_auto_hint()}'
            )


class LocalFilesImportStorageBase(LocalFilesMixin, ImportStorage):
    url_scheme = 'https'

    def can_resolve_url(self, url):
        return False

    recursive_scan = models.BooleanField(
        _('recursive scan'),

View on GitHub (pinned to 0b49e9b539)

Solutions

Set LOCAL_FILES_SERVING_ENABLED=true in the environment (docker: -e LOCAL_FILES_SERVING_ENABLED=true) and restart Label Studio
Set it in the docker-compose environment section or systemd unit and verify with `docker exec <container> printenv LOCAL_FILES_SERVING_ENABLED`
Confirm the value is the lowercase string "true"; the setting is parsed as a strict boolean, so 'True' or '1' may not enable it depending on version

Example fix

// before
docker run ... -e LOCAL_FILES_DOCUMENT_ROOT=/label-studio/data  # serving flag missing
// after
docker run ... -e LOCAL_FILES_DOCUMENT_ROOT=/label-studio/data -e LOCAL_FILES_SERVING_ENABLED=true

Defensive patterns

Strategy: validation

Validate before calling

import os
if os.environ.get('LOCAL_FILES_SERVING_ENABLED', '').lower() != 'true':
    raise SystemExit('Set LOCAL_FILES_SERVING_ENABLED=true and restart Label Studio before using local storage')

Try / catch

try:
    storage.validate_connection()
except ValidationError as e:
    if 'LOCAL_FILES_SERVING_ENABLED' in ';'.join(e.messages):
        logger.error('Enable local serving via env var and restart')
    else:
        raise

Prevention

Bake LOCAL_FILES_SERVING_ENABLED=true into docker-compose/systemd env for local-storage deployments
Use the exact lowercase string 'true'
Verify inside the container with printenv after restart
Understand this is an intentional security opt-in, not a bug

When it happens

Trigger: Creating or testing any Local Files storage while the LOCAL_FILES_SERVING_ENABLED environment variable is unset or set to anything other than 'true' (the setting resolves to False), after the path itself passed the existence and document-root checks.

Common situations: Fresh self-hosted installs where the operator only set LOCAL_FILES_DOCUMENT_ROOT but not the serving flag; Docker deployments missing the -e LOCAL_FILES_SERVING_ENABLED=true flag; upgrades where the flag became mandatory; users who set it to 'True'/'1' and expect case/format tolerance.

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

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