unslothai/unsloth · error · NativePathLeaseError

Native path contains invalid characters.

Error message

Native path contains invalid characters.

What it means

The path string contains a NUL byte (\x00), which cannot be a valid filesystem path on any supported OS (paths are NUL-terminated in C APIs). _reject_network_or_device_path() rejects it as invalid input before any stat is attempted. It exists to stop malformed or injection-style payloads early.

Source

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

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


def _same_native_path(resolved: Path, signed: Path) -> bool:
    try:
        return resolved.samefile(signed)
    except OSError:
        return os.path.normcase(str(resolved)) == os.path.normcase(str(signed))


def _optional_int(value: Any) -> int | None:

View on GitHub (pinned to 203007d190)

Solutions

1. Decode the payload and locate the NUL in canonical_path to confirm the source.
2. Fix the signer to validate canonical_path as clean UTF-8 with no control bytes before signing.
3. Regenerate the grant; the signed payload cannot be edited.
4. Add round-trip tests that assert the built path equals os.path-normalized expected value.

Example fix

// before (Rust)
let p = String::from_utf8_lossy(&buf); // buf may contain trailing \0

// after
let p = String::from_utf8(buf)?.trim_end_matches('\0').to_string();
assert!(Path::new(&p).is_absolute() && !p.contains('\0'));

def path_has_no_nul(path: str) -> bool:
    return '\x00' not in path

def is_clean_path_string(value: object) -> bool:
    return isinstance(value, str) and '\x00' not in value and value == value.strip('\x00')

try:
    grant = verify_native_path_lease(lease, operation='read')
except NativePathLeaseError as exc:
    if 'invalid characters' in str(exc):
        return respond(400, 'Corrupt grant; re-select the file to mint a fresh one.')
    raise

When it happens

Trigger: verify_native_path_lease() where str(path) contains \x00: signer embedded raw bytes into canonical_path; a test payload built from bytes buffers; corruption of the grant string or JSON payload with control characters.

Common situations: Rust signer writing non-UTF8 or fixed-width buffers into the path field; truncation/concat bugs producing embedded NULs; fuzzers feeding arbitrary bytes into path construction; JSON payloads built via string concatenation instead of a JSON serializer.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Native path grant contains invalid characters.
• Provider base URL contains invalid characters.
• Resume checkpoint uses a path from a different operating sys
• Resume checkpoint must be inside Unsloth outputs.
• The Hugging Face cache folder is invalid.

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