unslothai/unsloth · error · RuntimeError

Linked source is not a regular file

Error message

Linked source is not a regular file

What it means

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.

Source

Thrown at studio/backend/core/rag/folder_sync.py:1029

        raise RuntimeError("Linked folder root identity changed during scan")
    return found, identity


def _snapshot(root: str, metadata: dict) -> str:
    source = metadata["path"]
    resolved = os.path.realpath(source)
    if not _is_within(root, resolved):
        raise RuntimeError("File escaped the linked folder")
    # os.fdopen already forces this descriptor binary on Windows; O_BINARY only guards a raw os.read.
    flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_BINARY", 0)
    fd = os.open(source, flags)
    target = None
    try:
        ext = os.path.splitext(source)[1].lower()
        target = ensure_dir(rag_uploads_root()) / f"linked-{uuid.uuid4().hex}{ext}"
        before = os.fstat(fd)
        if not stat.S_ISREG(before.st_mode):
            raise RuntimeError("Linked source is not a regular file")
        expected = (
            metadata["size_bytes"],
            metadata["mtime_ns"],
            metadata["device"],
            metadata["inode"],
        )
        actual = (before.st_size, before.st_mtime_ns, before.st_dev, before.st_ino)
        # Only an identity os.fstat can reproduce is comparable here: os.scandir reports none at all
        # on Windows, and the os.lstat _scan falls back to disagrees with os.fstat on file systems
        # without stable file ids. Size and mtime still gate those, and the post-copy check below is
        # fstat to fstat either way.
        usable = metadata["inode"] not in (None, 0) and not metadata.get("identity_from_path")
        compared = 4 if usable else 2
        if actual[:compared] != expected[:compared]:
            raise RuntimeError("Linked source changed during reconciliation")
        if config.MAX_UPLOAD_BYTES and before.st_size > config.MAX_UPLOAD_BYTES:
            raise RuntimeError("Linked source exceeds the RAG file size limit")
        with os.fdopen(fd, "rb", closefd = False) as src, open(target, "xb") as dst:

View on GitHub (pinned to 203007d190)

Solutions

1. Remove the non-regular file from the linked folder and re-run sync.
2. Restrict linked folders to plain document trees, not runtime/FUSE trees containing special files.
3. If the platform lacks O_NOFOLLOW support so a symlink was followed, re-scan: the new entry is skipped as a symlink.

Example fix

# before: data/pipe is a FIFO created by a script
mkfifo /data/queue  # inside linked folder

# after
rm /data/queue  # keep only regular files inside the linked root

import os, stat

def is_plain_regular_file(path: str) -> bool:
    if os.path.islink(path):
        return False
    return stat.S_ISREG(os.stat(path).st_mode)

try:
    ingest_folder(folder_id)
except RuntimeError as e:
    if "not a regular file" in str(e):
        report_non_regular_entries(folder_id)  # list FIFOs/devices for cleanup
    else:
        raise

When it happens

Trigger: 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.

Common situations: Unix tools leaving FIFOs in data directories; /proc-like or FUSE filesystems exposing non-regular entries; adversarial replacement during the scan window.

Related errors

• Linked folder changed after it was selected
• File escaped the linked folder
• Linked folder no longer resolves to its registered path
• Linked folders in the same scope cannot overlap
• Linked folder root identity changed

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/e765f235c7ff8de0. Report an issue: GitHub.