{"record":{"id":"e765f235c7ff8de0","repo":"unslothai/unsloth","slug":"linked-source-is-not-a-regular-file","errorCode":null,"errorMessage":"Linked source is not a regular file","messagePattern":"Linked source is not a regular file","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/rag/folder_sync.py","lineNumber":1029,"sourceCode":"        raise RuntimeError(\"Linked folder root identity changed during scan\")\n    return found, identity\n\n\ndef _snapshot(root: str, metadata: dict) -> str:\n    source = metadata[\"path\"]\n    resolved = os.path.realpath(source)\n    if not _is_within(root, resolved):\n        raise RuntimeError(\"File escaped the linked folder\")\n    # os.fdopen already forces this descriptor binary on Windows; O_BINARY only guards a raw os.read.\n    flags = os.O_RDONLY | getattr(os, \"O_NOFOLLOW\", 0) | getattr(os, \"O_BINARY\", 0)\n    fd = os.open(source, flags)\n    target = None\n    try:\n        ext = os.path.splitext(source)[1].lower()\n        target = ensure_dir(rag_uploads_root()) / f\"linked-{uuid.uuid4().hex}{ext}\"\n        before = os.fstat(fd)\n        if not stat.S_ISREG(before.st_mode):\n            raise RuntimeError(\"Linked source is not a regular file\")\n        expected = (\n            metadata[\"size_bytes\"],\n            metadata[\"mtime_ns\"],\n            metadata[\"device\"],\n            metadata[\"inode\"],\n        )\n        actual = (before.st_size, before.st_mtime_ns, before.st_dev, before.st_ino)\n        # Only an identity os.fstat can reproduce is comparable here: os.scandir reports none at all\n        # on Windows, and the os.lstat _scan falls back to disagrees with os.fstat on file systems\n        # without stable file ids. Size and mtime still gate those, and the post-copy check below is\n        # fstat to fstat either way.\n        usable = metadata[\"inode\"] not in (None, 0) and not metadata.get(\"identity_from_path\")\n        compared = 4 if usable else 2\n        if actual[:compared] != expected[:compared]:\n            raise RuntimeError(\"Linked source changed during reconciliation\")\n        if config.MAX_UPLOAD_BYTES and before.st_size > config.MAX_UPLOAD_BYTES:\n            raise RuntimeError(\"Linked source exceeds the RAG file size limit\")\n        with os.fdopen(fd, \"rb\", closefd = False) as src, open(target, \"xb\") as dst:","sourceCodeStart":1011,"sourceCodeEnd":1047,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/rag/folder_sync.py#L1011-L1047","documentation":"After opening the source file (O_RDONLY|O_NOFOLLOW), _snapshot fstats the descriptor and requires S_ISREG. If the path now refers to a FIFO, device node, socket, or (where O_NOFOLLOW is unavailable, e.g. some Windows/network mounts) something other than a regular file, the snapshot aborts before copying — regular-file-only ingestion also protects _copy_exact's size-based loop.","triggerScenarios":"A scanned regular file replaced by a named pipe (mkfifo), a character device, or a socket between scan and snapshot; special files present because the scan's stat(follow_symlinks=False) accepted them on a platform that doesn't filter non-regular entries.","commonSituations":"Unix tools leaving FIFOs in data directories; /proc-like or FUSE filesystems exposing non-regular entries; adversarial replacement during the scan window.","solutions":["Remove the non-regular file from the linked folder and re-run sync.","Restrict linked folders to plain document trees, not runtime/FUSE trees containing special files.","If the platform lacks O_NOFOLLOW support so a symlink was followed, re-scan: the new entry is skipped as a symlink."],"exampleFix":"# before: data/pipe is a FIFO created by a script\nmkfifo /data/queue  # inside linked folder\n\n# after\nrm /data/queue  # keep only regular files inside the linked root","handlingStrategy":"validation","validationCode":"import os, stat\n\ndef is_plain_regular_file(path: str) -> bool:\n    if os.path.islink(path):\n        return False\n    return stat.S_ISREG(os.stat(path).st_mode)","typeGuard":null,"tryCatchPattern":"try:\n    ingest_folder(folder_id)\nexcept RuntimeError as e:\n    if \"not a regular file\" in str(e):\n        report_non_regular_entries(folder_id)  # list FIFOs/devices for cleanup\n    else:\n        raise","preventionTips":["Keep only regular document files in linked folders; no FIFOs, sockets, device nodes.","Pre-scan the tree for non-regular entries before linking.","Don't link runtime/FUSE trees that expose special files."],"tags":["rag","folder-sync","filesystem","security","toctou"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}