{"record":{"id":"e21db6f36a8d505a","repo":"HumanSignal/label-studio","slug":"failed-to-read-file-path-str-e","errorCode":null,"errorMessage":"Failed to read file {path}: {str(e)}","messagePattern":"Failed to read file (.+?): (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"label_studio/io_storages/localfiles/models.py","lineNumber":168,"sourceCode":"\n    def get_data(self, key) -> list[StorageObject]:\n        path = Path(key)\n        if self.use_blob_urls:\n            # include self-hosted links pointed to local resources via\n            # {settings.HOSTNAME}/data/local-files?d=<path/to/local/dir>\n            document_root = Path(settings.LOCAL_FILES_DOCUMENT_ROOT)\n            relative_path = str(path.relative_to(document_root))\n            task = {\n                settings.DATA_UNDEFINED_NAME: f'{settings.HOSTNAME}/data/local-files/?d={quote(str(relative_path))}'\n            }\n            return [StorageObject(key=key, task_data=task)]\n\n        try:\n            with open(path, 'rb') as f:\n                blob = f.read()\n                return load_tasks_json(blob, key)\n        except OSError as e:\n            raise ValueError(f'Failed to read file {path}: {str(e)}')\n\n    def scan_and_create_links(self):\n        return self._scan_and_create_links(LocalFilesImportStorageLink)\n\n    class Meta:\n        abstract = True\n\n\nclass LocalFilesImportStorage(ProjectStorageMixin, LocalFilesImportStorageBase):\n    class Meta:\n        abstract = False\n\n\nclass LocalFilesExportStorage(LocalFilesMixin, ExportStorage):\n    def save_annotation(self, annotation):\n        logger.debug(f'Creating new object on {self.__class__.__name__} Storage {self} for annotation {annotation}')\n        ser_annotation = self._get_serialized_data(annotation)\n","sourceCodeStart":150,"sourceCodeEnd":186,"githubUrl":"https://github.com/HumanSignal/label-studio/blob/0b49e9b53917880baf1dd85d574fe5541a9aafb2/label_studio/io_storages/localfiles/models.py#L150-L186","documentation":"When Local Files import storage reads a task file that is not in use_blob_urls mode, it opens the file and parses it with load_tasks_json. If the open/read raises OSError (permission denied, file deleted between scan and read, I/O error), get_data wraps it in a ValueError carrying the OS message. This surfaces during storage sync when converting scanned files into tasks.","triggerScenarios":"Syncing a Local Files import storage where a scanned file cannot be opened: file permissions unreadable by the Label Studio process user, the file was removed after the directory scan, a broken symlink, or a disk/device error during read.","commonSituations":"Files owned by root while Label Studio runs as another user in Docker; NFS/bind-mount permission mismatches; race between dataset regeneration and a sync; files with restrictive modes like 0600.","solutions":["Fix file permissions so the Label Studio process user can read them (chmod/chown, or match UID in the container)","Re-scan/re-sync so deleted files are removed from the pending list, and remove stale/broken symlinks from the directory","Check the OS message embedded in the error (e.g. 'Permission denied' vs 'No such file or directory') to pick between permission and missing-file fixes","If the files are raw images/blobs rather than task JSON, enable use_blob_urls so they are referenced as URLs instead of parsed"],"exampleFix":"// before\n# host file: -rw------- root root task.json, Label Studio runs as appuser -> OSError\n// after\nsudo chown -R 10001:10001 /label-studio/data/dataset1   # or chmod o+r the task files","handlingStrategy":"try-catch","validationCode":"import os\npath = '/label-studio/data/dataset1/task.json'\nif not os.path.isfile(path) or not os.access(path, os.R_OK):\n    raise SystemExit(f'File missing or unreadable by Label Studio user: {path}')","typeGuard":"def is_readable_file(path: str) -> bool:\n    from pathlib import Path\n    p = Path(path)\n    return p.is_file() and os.access(p, os.R_OK)","tryCatchPattern":"try:\n    tasks = storage.get_data(key)\nexcept ValueError as e:\n    logger.error('Local file read failed during sync: %s — check permissions/staleness', e)","preventionTips":["Run the Label Studio process with a UID that owns or can read the data directory","Avoid mutating dataset files during a sync","Clean broken symlinks from storage directories","Enable use_blob_urls for binary assets instead of JSON parsing"],"tags":["filesystem","io","permissions","sync"],"backgroundTag":"file-read-failed","analyzedSha":"0b49e9b53917880baf1dd85d574fe5541a9aafb2","analyzedAt":"2026-08-29T00:39:52.578Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}