HKUDS/DeepTutor · error · ValueError

This folder is outside the locations allowed for linking.

Error message

This folder is outside the locations allowed for linking.

What it means

Raised when an allowlist of linkable roots is configured (allowed_link_roots()) and the resolved folder (symlinks resolved) does not fall under any allowed root. With no allowlist configured, any existing directory is permitted — the self-hosted default.

Source

Thrown at deeptutor/services/rag/linked_kb.py:109

def assert_path_allowed(folder_path: str) -> Path:
    """Resolve ``folder_path`` and enforce the optional root allowlist.

    Returns the resolved absolute path. Raises ``ValueError`` if the folder is
    missing/not a directory, or escapes the configured allowlist (symlinks are
    resolved first so they can't tunnel out). With no allowlist set, any
    existing directory is permitted — the self-hosted default.
    """
    folder = Path(folder_path).expanduser()
    if not folder.exists():
        raise ValueError(f"Folder does not exist: {folder}")
    if not folder.is_dir():
        raise ValueError(f"Not a directory: {folder}")
    resolved = folder.resolve()

    roots = allowed_link_roots()
    if roots and not any(_is_within(resolved, root) for root in roots):
        raise ValueError("This folder is outside the locations allowed for linking.")
    return resolved


def _is_within(path: Path, root: Path) -> bool:
    try:
        return path == root or root in path.parents
    except OSError:
        return False


def probe_linked_folder(folder_path: str, provider: str) -> ProbeResult:
    """Inspect ``folder_path`` for a ready ``provider`` index.

    Always returns a :class:`ProbeResult` (never raises): ``error`` set means
    the folder cannot be linked; ``warnings`` are non-fatal cautions the user
    confirms. The caller is responsible for any path-jail / access checks.
    """
    provider = normalize_provider_name(provider)

View on GitHub (pinned to 3e82f13042)

Solutions

1. Move or symlink the folder from inside an allowed root (a real path under the root).
2. Add the folder's parent to the configured link roots setting and retry.
3. If you are the self-hosted admin and want permissive behavior, clear the allowlist setting.
4. Verify with Path(folder).resolve() which real path is being evaluated.

Example fix

# before: /srv/data outside allowlist ['/home/user']
await connect_linked_folder_route(session, kb, "/srv/data/vault")
# after: add to settings
allowed_link_roots: ["/home/user", "/srv/data"]

from pathlib import Path
resolved = Path(folder_path).expanduser().resolve()
roots = allowed_link_roots()
if roots and not any(resolved == r or r in resolved.parents for r in roots):
    raise InputError("outside allowed link roots")

When it happens

Trigger: DEEPTUTOR_LINK_ROOTS (or equivalent settings key) is set, and the user links a folder outside those roots; a symlink inside an allowed root points outside it (resolved before checking, so it's rejected).

Common situations: Hardened/multi-user deployments that restrict linking to specific directories; symlinks from an allowed directory into / or another user's home; misunderstanding that symlinks are resolved, so tricks to escape the allowlist fail by design.

Related errors

• Folder does not exist: {folder}
• Not a directory: {folder}
• Invalid math animator config: {details}
• Invalid folder path
• Access denied

AI-assisted analysis of HKUDS/DeepTutor@3e82f13042 (2026-08-27). Data as JSON: /api/errors/6b88422d074d86f6. Report an issue: GitHub.