unslothai/unsloth · error · HTTPException

Invalid path

Error message

Invalid path

What it means

Raised as a 400 by _resolve_browse_target when Path.resolve() on a matched child raises an OSError — the filesystem itself refused to canonicalize the component (e.g. too many symlinks, name too long, I/O error). The warning log names the component and parent directory; the client sees only the generic 'Invalid path'.

Source

Thrown at studio/backend/routes/models.py:1695

        current = root
        for part in parts:
            child = _match_browse_child(current, part)
            if child is None:
                raise HTTPException(
                    status_code = 404,
                    detail = f"Path does not exist: {os.path.basename(requested_path)}",
                )
            try:
                resolved_child = child.resolve()
            except OSError as exc:
                logger.warning(
                    "browse-folders: invalid path component %r under %s: %s",
                    part,
                    current,
                    exc,
                    exc_info = True,
                )
                raise HTTPException(
                    status_code = 400,
                    detail = "Invalid path",
                ) from exc
            if not _is_path_inside_allowlist(resolved_child, resolved_roots):
                raise HTTPException(
                    status_code = 403,
                    detail = (
                        "Path is not in the browseable allowlist. Register it via "
                        "POST /api/models/scan-folders first, or pick a directory "
                        "under your home folder."
                    ),
                )
            if contains_sensitive_path_component(str(resolved_child)):
                raise HTTPException(
                    status_code = 403,
                    detail = "Credential or configuration directories are not browseable.",
                )
            if is_denied_system_path(str(resolved_child)):

View on GitHub (pinned to 203007d190)

Solutions

1. Inspect the backend log line 'invalid path component' to identify which segment failed.
2. Break symlink cycles (find . -type l -xtype l) or rename over-length components.
3. If the mount is failing, remount or fsck the volume and retry browsing.

import os

def resolvable(path: str) -> bool:
    try:
        os.path.realpath(path)
        return True
    except OSError:
        return False

if not resolvable(models_dir):
    raise ValueError('path cannot be resolved — check for symlink loops or over-long names')

try:
    entries = browse(path)
except HTTPError as e:
    if e.response.status_code == 400 and e.response.json()['detail'] == 'Invalid path':
        show_user('That folder cannot be opened (bad symlink or invalid name). Pick another location.')
    else: raise

When it happens

Trigger: Browsing a path containing a symlink loop (ELOOP), a component exceeding NAME_MAX, or resolve() hitting an I/O error on a failing disk/mount.

Common situations: Cyclic symlinks inside a models directory; extremely long auto-generated folder names; a flaky external drive returning errors during path resolution.

Related errors

• Permission denied reading {current.name}
• Could not read {os.path.basename(str(current))}
• Could not read {os.path.basename(str(target))}
• GGUF conversion produced a symlink, refusing to relocate it:
• Linked folder is no longer a regular directory

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