unslothai/unsloth · warning · ValueError

System directories are not allowed

Error message

System directories are not allowed

What it means

ValueError raised when is_denied_system_path(normalized) classifies the path as a system directory (e.g. /usr, /bin, /etc, /Windows, /System32, Program Files). These trees contain OS binaries and machine-critical data; scanning them is slow, pointless for RAG, and can touch executable/system state, so they are denied after the sensitive-component check as the last policy gate before the path is accepted.

Source

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

        is_denied_system_path,
    )
    from utils.paths.external_media import is_local_filesystem_root

    if not os.path.isdir(normalized):
        raise ValueError("Path must be a directory, not a file")
    if not os.access(normalized, os.R_OK | os.X_OK):
        raise ValueError("Path is not readable")
    if is_local_filesystem_root(normalized):
        raise ValueError("The filesystem root cannot be registered")
    try:
        if Path(normalized) == Path.home().resolve():
            raise ValueError("The entire home folder cannot be registered")
    except RuntimeError:
        pass
    if contains_sensitive_path_component(normalized):
        raise ValueError("Credential or configuration directories are not allowed")
    if is_denied_system_path(normalized):
        raise ValueError("System directories are not allowed")
    return normalized


def _root_identity(root: str) -> tuple[int, int]:
    try:
        root_stat = os.lstat(root)
    except OSError as exc:
        raise RuntimeError("Linked folder is unavailable") from exc
    if stat.S_ISLNK(root_stat.st_mode) or not stat.S_ISDIR(root_stat.st_mode):
        raise RuntimeError("Linked folder is no longer a regular directory")
    if os.path.normcase(os.path.realpath(root)) != os.path.normcase(root):
        raise RuntimeError("Linked folder no longer resolves to its registered path")
    return root_stat.st_dev, root_stat.st_ino


def _store_identity(identity: tuple[int, int]) -> tuple[int | str, int | str]:
    return tuple(value if value <= _SQLITE_INTEGER_MAX else f"x{value:x}" for value in identity)

View on GitHub (pinned to 203007d190)

Solutions

1. Copy the specific documentation files you need into a user folder and register that.
2. Choose a user-writable location (~/Documents, /srv/data, D:\\Docs) for scanned content.
3. Check is_denied_system_path's deny list in hub.storage.scan_folders to see exactly which roots are blocked.

Example fix

# before
validate_folder_path('/usr/share/doc')

# after
# copy desired docs out of system tree first
validate_folder_path('/home/me/Documents/system-docs')

from hub.storage.scan_folders import is_denied_system_path
import os

def folder_is_not_system_path(path: str) -> bool:
    normalized = os.path.realpath(os.path.abspath(os.path.expanduser(path)))
    return not is_denied_system_path(normalized)

try:
    validate_folder_path(path)
except ValueError as e:
    if "System directories" not in str(e):
        raise
    return bad_request("system directories cannot be indexed; copy docs to a user folder")

When it happens

Trigger: Registering /usr/share/docs, /etc, C:\\Windows, or a Program Files application folder; paths that realpath resolves into a system tree via a bind mount or junction.

Common situations: Users trying to index software documentation shipped under /usr/share; Windows users selecting Program Files; containers where the app folder is under /usr/lib.

Related errors

• Symbolic-link folders are not allowed
• Credential or configuration directories are not allowed
• {_cn_fs.reason}
• Provider base URL points at a private address, which is disa
• Non-GGUF video loads are limited to unsloth/* repos, the off

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