{"record":{"id":"7aa2d248b1c0c854","repo":"unslothai/unsloth","slug":"linked-folder-is-unavailable","errorCode":null,"errorMessage":"Linked folder is unavailable","messagePattern":"Linked folder is unavailable","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/rag/folder_sync.py","lineNumber":169,"sourceCode":"    if is_local_filesystem_root(normalized):\n        raise ValueError(\"The filesystem root cannot be registered\")\n    try:\n        if Path(normalized) == Path.home().resolve():\n            raise ValueError(\"The entire home folder cannot be registered\")\n    except RuntimeError:\n        pass\n    if contains_sensitive_path_component(normalized):\n        raise ValueError(\"Credential or configuration directories are not allowed\")\n    if is_denied_system_path(normalized):\n        raise ValueError(\"System directories are not allowed\")\n    return normalized\n\n\ndef _root_identity(root: str) -> tuple[int, int]:\n    try:\n        root_stat = os.lstat(root)\n    except OSError as exc:\n        raise RuntimeError(\"Linked folder is unavailable\") from exc\n    if stat.S_ISLNK(root_stat.st_mode) or not stat.S_ISDIR(root_stat.st_mode):\n        raise RuntimeError(\"Linked folder is no longer a regular directory\")\n    if os.path.normcase(os.path.realpath(root)) != os.path.normcase(root):\n        raise RuntimeError(\"Linked folder no longer resolves to its registered path\")\n    return root_stat.st_dev, root_stat.st_ino\n\n\ndef _store_identity(identity: tuple[int, int]) -> tuple[int | str, int | str]:\n    return tuple(value if value <= _SQLITE_INTEGER_MAX else f\"x{value:x}\" for value in identity)\n\n\ndef _file_identity(metadata: dict) -> tuple[int | str, int | str]:\n    return _store_identity((metadata[\"device\"], metadata[\"inode\"]))\n\n\ndef _load_identity(device_id: int | str, file_id: int | str) -> tuple[int, int]:\n    def load(value: int | str) -> int:\n        return (","sourceCodeStart":151,"sourceCodeEnd":187,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/rag/folder_sync.py#L151-L187","documentation":"RuntimeError raised by _root_identity when os.lstat on an already-registered linked folder raises OSError — the folder has disappeared or become unreachable since registration. This runs during sync operations on persisted links (not initial validation, which raises ValueError), so the distinction signals drift from a previously valid state: unmounted drive, deleted folder, or revoked network share.","triggerScenarios":"A periodic sync iterating registered links when one folder's volume is unmounted (USB unplugged, NFS share down) or the folder was deleted; container restart where a host bind-mount source is gone.","commonSituations":"Removable media registered then removed; laptop sleep/wake dropping network mounts; folders deleted by backup/cleanup scripts; docker volumes removed while the DB still references them.","solutions":["Remount or restore the missing volume, then retry the sync.","If the folder is gone permanently, unregister (delete) the linked-folder record from RAG settings so sync stops failing.","Catch this RuntimeError per-folder in sync loops and skip/quarantine the dead link instead of aborting the whole sync.","Prefer stable, always-mounted paths for registered folders."],"exampleFix":"# before\nfor link in registered_folders():\n    sync_folder(link)  # one dead volume aborts the loop\n\n# after\nfor link in registered_folders():\n    try:\n        sync_folder(link)\n    except RuntimeError as e:\n        if 'unavailable' not in str(e):\n            raise\n        logger.warning('skipping unavailable folder %s', link)\n        mark_quarantined(link)","handlingStrategy":"try-catch","validationCode":"import os\n\ndef folder_still_available(root: str) -> bool:\n    try:\n        os.lstat(root)\n        return True\n    except OSError:\n        return False\n\n# before each sync:\n# if not folder_still_available(link.path): skip_and_quarantine(link)","typeGuard":null,"tryCatchPattern":"for link in registered_folders():\n    try:\n        sync(link)\n    except RuntimeError as e:\n        if \"Linked folder is unavailable\" not in str(e):\n            raise\n        logger.warning(\"folder %s unavailable; skipping\", link.path)\n        quarantine(link)  # keep syncing the rest","preventionTips":["Register only folders on always-mounted storage; avoid removable media for permanent links.","Run an availability pre-check per folder before each sync batch.","Surface a per-folder 'unavailable' state in the UI instead of failing the whole sync."],"tags":["filesystem","mounts","sync","rag","drift"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}