unslothai/unsloth · error · NativePathLeaseError

Network paths are not supported for native grants.

Error message

Network paths are not supported for native grants.

What it means

On Windows, a path with the \\?\ extended-length prefix was rejected because the drive component after the prefix is not a local drive letter (X:\). The backend refuses network targets (UNC paths, mapped servers, devices exposed via the extended prefix) because native path grants must reference local volumes the backend can stat and pin by identity. _reject_network_or_device_path() normalizes slashes and lowercases before testing.

Source

Thrown at studio/backend/utils/native_path_leases.py:407

        if len(_NATIVE_PATH_LABELS) > _MAX_NATIVE_PATH_LABELS:
            excess = len(_NATIVE_PATH_LABELS) - _MAX_NATIVE_PATH_LABELS
            for stale_path in list(_NATIVE_PATH_LABELS.keys())[:excess]:
                _NATIVE_PATH_LABELS.pop(stale_path, None)
        if path in _NATIVE_PATH_REDACTIONS:
            return
        _NATIVE_PATH_REDACTIONS.append(path)
        del _NATIVE_PATH_REDACTIONS[:-_MAX_NATIVE_PATH_REDACTIONS]


def _reject_network_or_device_path(path: Path) -> None:
    text = str(path)
    if os.name == "nt":
        normalized = text.replace("/", "\\").lower()
        if normalized.startswith("\\\\?\\"):
            rest = normalized[4:]
            is_local_drive = len(rest) >= 3 and rest[0].isalpha() and rest[1:3] == ":\\"
            if not is_local_drive:
                raise NativePathLeaseError("Network paths are not supported for native grants.")
        elif normalized.startswith("\\\\"):
            raise NativePathLeaseError("Network paths are not supported for native grants.")
    if os.name != "nt":
        for root in ("/dev", "/proc", "/sys"):
            if path.is_relative_to(root):
                raise NativePathLeaseError("Device and virtual filesystem paths are not supported.")
    if "\x00" in text:
        raise NativePathLeaseError("Native path contains invalid characters.")


def _b64decode(value: str) -> bytes:
    try:
        padding = "=" * (-len(value) % 4)
        return base64.urlsafe_b64decode((value + padding).encode("ascii"))
    except (UnicodeEncodeError, binascii.Error, ValueError) as exc:
        raise NativePathLeaseError("Native path grant has an invalid format.") from exc

View on GitHub (pinned to 203007d190)

Solutions

1. Copy the file to a local drive (e.g. C:\Users\...\model.gguf) and select the local copy.
2. Map the network share to a drive letter and re-select via that letter only if the backend truly can stat it locally (preferred: copy local).
3. If this is a legitimate product gap, add explicit network-share support to both signer and verifier rather than bypassing the check.
4. Check the normalized path from the grant payload to confirm which prefix form triggered it.

Example fix

# before
selected: \\?\UNC\nas\models\model.gguf   -> rejected

# after
copy \\nas\models\model.gguf C:\models\model.gguf
select C:\models\model.gguf            -> accepted

import os

def is_local_windows_prefixed_path(path: str) -> bool:
    if os.name != 'nt':
        return True
    n = path.replace('/', '\\').lower()
    if n.startswith('\\\\?\\'):
        rest = n[4:]
        return len(rest) >= 3 and rest[0].isalpha() and rest[1:3] == ':\\'
    return True

def is_local_drive_path(path: str) -> bool:
    n = path.replace('/', '\\').lower()
    if n.startswith('\\\\?\\'):
        rest = n[4:]
        return len(rest) >= 3 and rest[0].isalpha() and rest[1:3] == ':\\'
    return not n.startswith('\\\\') and (len(n) < 2 or n[1] == ':')

try:
    grant = verify_native_path_lease(lease, operation='read')
except NativePathLeaseError as exc:
    if 'Network paths are not supported' in str(exc):
        return respond(400, 'Copy the file to a local drive and re-select it.')
    raise

When it happens

Trigger: verify_native_path_lease() on Windows with a signed canonical_path like \\?\UNC\server\share\file.gguf or \\?\Volume{guid}\... where the segment after \\?\ is not '<letter>:\'. Mapped network drives are also caught in prefix form.

Common situations: User picks a file on a NAS or network share through the desktop picker; WSL paths surfaced as \\?\UNC\wsl$\...; iSCSI/network volumes mounted without a drive letter; long-path tooling that rewrites paths into \\?\ form.

Related errors

• extra llama-server args are too long for a Windows command l
• base_precision={mode!r} is not available on this host: torch
• Native path grant is required.
• Dropped file could not be read.
• Native folder grant has no stable identity.

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