HumanSignal/label-studio · error · ValidationError

Absolute local path "{self.path}" does not exist

Error message

Absolute local path "{self.path}" does not exist

What it means

Label Studio's Local Files storage requires that the configured 'path' be an absolute directory that exists on the host filesystem. validate_connection checks path.exists() and raises Django ValidationError if it does not. This runs inside the container/host running Label Studio, not on the developer's machine, so a path that exists locally may not exist for the server.

Source

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

    @staticmethod
    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 '

View on GitHub (pinned to 0b49e9b539)

Solutions

1. Create the directory on the Label Studio host (mkdir -p <path>) and, for Docker, mount it as a volume (-v /your/data:/label-studio/data/local-files/?d=your-data style mount)
2. Use a fully qualified absolute path including the leading slash, verified with ls on the actual server/container
3. Check spelling and case of the path on a case-sensitive filesystem
4. Ensure LOCAL_FILES_DOCUMENT_ROOT is set and the path you pass lives beneath it

Example fix

// before
{ "path": "mydata/dataset1" }        // relative -> Path('mydata/dataset1').exists() is False
// after
{ "path": "/label-studio/data/local-files/mydata/dataset1" }

from pathlib import Path
p = Path('/label-studio/data/dataset1')
if not p.is_absolute() or not p.exists():
    raise SystemExit(f'Storage path must be an existing absolute path: {p}')

try:
    storage.validate_connection()
except ValidationError as e:
    if 'does not exist' in ';'.join(e.messages):
        logger.error('Local path missing on the SERVER host (check Docker mounts): %s', e)
    else:
        raise

When it happens

Trigger: Saving or testing a Local Files import/export storage via the API (serializer.validate -> storage.validate_connection) where the normalized path does not exist on the Label Studio host: a relative path, a typo, a directory deleted after setup, or a host-only path inside a Docker container without the volume mounted.

Common situations: Docker deployments where /label-studio/data is not volume-mounted; path typed without leading '/' so it resolves incorrectly; running Label Studio locally with a path from a colleague's machine; case-sensitivity mismatch on Linux (e.g. /Data vs /data).

Related errors

• Absolute local path "{self.path}" cannot be the same as LOCA
• Absolute local path "{self.path}" must be a subdirectory of
• User filter list exceeds maximum size of {settings.DATA_MANA
• Invalid or missing serializer class
• No blobs found in {bucket_name}/{prefix} or prefix doesn't e

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