HumanSignal/label-studio · error · ValidationError

Absolute local path "{self.path}" cannot be the same as LOCA

Error message

Absolute local path "{self.path}" cannot be the same as LOCAL_FILES_DOCUMENT_ROOT="{settings.LOCAL_FILES_DOCUMENT_ROOT}" by security reasons. Please add a subdirectory. For example: "{example_path}".

What it means

Label Studio forbids configuring Local Files storage with a path equal to LOCAL_FILES_DOCUMENT_ROOT itself. Exposing the whole document root would let users browse every served file, so validate_connection rejects it with a Django ValidationError. The fix is to point the storage at a subdirectory of the document root.

Source

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

    def community_auto_hint():
        if settings.VERSION_EDITION == 'Community':
            return (
                ' Community tip: create a "mydata" or "label-studio-data" directory next to the Label Studio '
                'command to auto-enable LOCAL_FILES_DOCUMENT_ROOT when the environment variables are unset.'
            )
        return ''

    def validate_connection(self):
        normalized_path = self._get_storage_path_or_raise(ValidationError)
        self.path = normalized_path
        path = Path(normalized_path)
        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'

View on GitHub (pinned to 0b49e9b539)

Solutions

Create and use a subdirectory under the document root, e.g. <DOCUMENT_ROOT>/dataset1, and pass that as the storage path
If everything currently sits in the document root, move datasets into dedicated subdirectories
Verify LOCAL_FILES_DOCUMENT_ROOT is set to the intended base (not the dataset dir itself) so the storage path differs

Example fix

// before
{ "path": "/label-studio/data" }   // == LOCAL_FILES_DOCUMENT_ROOT -> rejected
// after
{ "path": "/label-studio/data/dataset1" }

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path
p, root = Path(path), Path('/label-studio/data')
if p == root:
    raise SystemExit('Storage path must be a SUBDIRECTORY of LOCAL_FILES_DOCUMENT_ROOT, not the root itself')

Try / catch

try:
    storage.validate_connection()
except ValidationError as e:
    if 'cannot be the same as' in ';'.join(e.messages):
        logger.error('Point the storage at e.g. %s', Path(root) / 'dataset1')
    else:
        raise

Prevention

Treat LOCAL_FILES_DOCUMENT_ROOT as a container, never a storage target
Organize datasets one level below the document root
Read the error text — it suggests the exact example path

When it happens

Trigger: Creating/updating a Local Files storage where the 'path' field, after normalization, is exactly the value of the LOCAL_FILES_DOCUMENT_ROOT setting (e.g. both are '/label-studio/data').

Common situations: Copy-pasting the LOCAL_FILES_DOCUMENT_ROOT value into the storage path field; thinking the document root itself is the dataset folder; Docker setups where only one directory exists so users point at the mount root.

Related errors

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