{"record":{"id":"806b0c4a024919e1","repo":"HumanSignal/label-studio","slug":"serving-local-files-from-the-host-filesystem-can-b","errorCode":null,"errorMessage":"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()}","messagePattern":"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(.+?)","errorType":"validation","errorClass":"ValidationError","httpStatus":400,"severity":"error","filePath":"label_studio/io_storages/localfiles/models.py","lineNumber":100,"sourceCode":"        document_root = Path(settings.LOCAL_FILES_DOCUMENT_ROOT)\n        example_path = Path(settings.LOCAL_FILES_DOCUMENT_ROOT) / 'dataset1'\n\n        if not path.exists():\n            raise ValidationError(f'Absolute local path \"{self.path}\" does not exist')\n        if document_root == path:\n            raise ValidationError(\n                f'Absolute local path \"{self.path}\" cannot be the same as '\n                f'LOCAL_FILES_DOCUMENT_ROOT=\"{settings.LOCAL_FILES_DOCUMENT_ROOT}\" by security reasons. Please add a subdirectory. '\n                f'For example: \"{example_path}\".'\n            )\n        if document_root not in path.parents:\n            raise ValidationError(\n                f'Absolute local path \"{self.path}\" must be a subdirectory of '\n                f'LOCAL_FILES_DOCUMENT_ROOT=\"{settings.LOCAL_FILES_DOCUMENT_ROOT}\" by security reasons. '\n                f'For example: \"{example_path}\".'\n            )\n        if settings.LOCAL_FILES_SERVING_ENABLED is False:\n            raise ValidationError(\n                'Serving local files from the host filesystem can be a security risk, so '\n                'LOCAL_FILES_SERVING_ENABLED is disabled by default. '\n                'To enable Local Files storage, set the LOCAL_FILES_SERVING_ENABLED environment '\n                'variable to \"true\" and restart Label Studio. See '\n                'https://labelstud.io/guide/storage.html#Local-storage for details.'\n                '\\n\\n'\n                f'{self.community_auto_hint()}'\n            )\n\n\nclass LocalFilesImportStorageBase(LocalFilesMixin, ImportStorage):\n    url_scheme = 'https'\n\n    def can_resolve_url(self, url):\n        return False\n\n    recursive_scan = models.BooleanField(\n        _('recursive scan'),","sourceCodeStart":82,"sourceCodeEnd":118,"githubUrl":"https://github.com/HumanSignal/label-studio/blob/0b49e9b53917880baf1dd85d574fe5541a9aafb2/label_studio/io_storages/localfiles/models.py#L82-L118","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\ndocker run ... -e LOCAL_FILES_DOCUMENT_ROOT=/label-studio/data  # serving flag missing\n// after\ndocker run ... -e LOCAL_FILES_DOCUMENT_ROOT=/label-studio/data -e LOCAL_FILES_SERVING_ENABLED=true","handlingStrategy":"validation","validationCode":"import os\nif os.environ.get('LOCAL_FILES_SERVING_ENABLED', '').lower() != 'true':\n    raise SystemExit('Set LOCAL_FILES_SERVING_ENABLED=true and restart Label Studio before using local storage')","typeGuard":null,"tryCatchPattern":"try:\n    storage.validate_connection()\nexcept ValidationError as e:\n    if 'LOCAL_FILES_SERVING_ENABLED' in ';'.join(e.messages):\n        logger.error('Enable local serving via env var and restart')\n    else:\n        raise","preventionTips":["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"],"tags":["security","configuration","environment","local-storage"],"backgroundTag":"missing-env-var","analyzedSha":"0b49e9b53917880baf1dd85d574fe5541a9aafb2","analyzedAt":"2026-08-29T00:39:52.578Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}