unslothai/unsloth · warning · ValueError

The entire home folder cannot be registered

Error message

The entire home folder cannot be registered

What it means

ValueError raised when the normalized path equals the resolved user home directory (Path.home().resolve()). The home folder as a whole contains credential/config subdirectories and huge caches, so registering it wholesale is denied even though individual subfolders may be fine. The check is wrapped in try/except RuntimeError (pass) to tolerate environments where the home cannot be resolved (e.g. deleted home dir), degrading to the later component checks.

Source

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

    uploads_root = os.path.realpath(str(rag_uploads_root()))
    if _paths_overlap(_path_key(normalized), _path_key(uploads_root)):
        raise ValueError("The managed RAG uploads folder cannot be linked")

    from hub.storage.scan_folders import (
        contains_sensitive_path_component,
        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")

View on GitHub (pinned to 203007d190)

Solutions

1. Register the specific subfolder containing documents, e.g. ~/Documents or ~/Documents/rag.
2. If many folders under home are needed, register each one individually.
3. In UIs, pre-select a subfolder and reject a selection equal to the home path.

Example fix

# before
validate_folder_path('~')

# after
validate_folder_path('~/Documents')

import os
from pathlib import Path

def folder_is_not_home(path: str) -> bool:
    normalized = os.path.realpath(os.path.abspath(os.path.expanduser(path)))
    try:
        return Path(normalized) != Path.home().resolve()
    except RuntimeError:
        return True

try:
    validate_folder_path(path)
except ValueError as e:
    if "home folder" not in str(e):
        raise
    return bad_request("select a subfolder (e.g. Documents), not your entire home")

When it happens

Trigger: Calling validate_folder_path('~') or the literal home path '/home/user' or '/Users/user'; a realpath that collapses (e.g. '~/.') back to home; folder pickers opened at home where the user confirms unchanged.

Common situations: Users wanting to index all their documents by linking home; cross-platform configs where '~' expansion lands exactly on home; freshly created accounts whose Documents live directly under home.

Related errors

• The filesystem root cannot be registered
• Path cannot be empty
• Symbolic-link folders are not allowed
• Path does not exist
• The managed RAG uploads folder cannot be linked

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