unslothai/unsloth · error · NativePathLeaseError

Native path grant has an invalid format.

Error message

Native path grant has an invalid format.

What it means

_split_lease() was given a lease that is not a string (e.g. a dict, bytes, or None passed as a non-falsy object like a list). The grant must be a single ASCII string of the form 'payload.signature'; anything with a different Python type is rejected before parsing.

Source

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

        with _NATIVE_PATH_ENV_LOCK:
            encoded = os.environ.get(LEASE_SECRET_ENV)
            if encoded is None and _SCRUB_SAVED_SECRET is not None:
                encoded = _SCRUB_SAVED_SECRET
        if not encoded:
            raise NativePathLeaseError("Native path grants require the managed desktop backend.")
        try:
            secret = _b64decode(encoded)
        except Exception as exc:
            raise NativePathLeaseError("Native path grant secret is invalid.") from exc
        if len(secret) < _MIN_LEASE_SECRET_BYTES:
            raise NativePathLeaseError("Native path grant secret is invalid.")
        _CACHED_LEASE_SECRET = secret
        return secret


def _split_lease(lease: str) -> tuple[str, str]:
    if not isinstance(lease, str):
        raise NativePathLeaseError("Native path grant has an invalid format.")
    try:
        lease.encode("ascii")
    except UnicodeEncodeError as exc:
        raise NativePathLeaseError("Native path grant has an invalid format.") from exc
    parts = lease.split(".")
    if len(parts) != 2 or not parts[0] or not parts[1]:
        raise NativePathLeaseError("Native path grant has an invalid format.")
    return parts[0], parts[1]


def _decode_payload(payload_b64: str) -> dict[str, Any]:
    try:
        payload = json.loads(_b64decode(payload_b64).decode("utf-8"))
    except Exception as exc:
        raise NativePathLeaseError("Native path grant payload is invalid.") from exc
    if not isinstance(payload, dict):
        raise NativePathLeaseError("Native path grant payload is invalid.")
    return payload

View on GitHub (pinned to 203007d190)

Solutions

1. Extract the actual string: use body['lease'] (or the request field your API defines), not the whole body object.
2. On the client, ensure the JSON value for the lease key is a plain string.
3. Add an isinstance(lease, str) assertion at the API boundary to fail with a clearer message.

Example fix

# before
verify_native_path_lease(payload, operation="read")  # passed whole dict

# after
verify_native_path_lease(payload.get("lease"), operation="read")

def extract_lease(body):
    lease = body.get("lease") if isinstance(body, dict) else None
    return lease if isinstance(lease, str) and lease else None

def is_lease(value: object) -> bool:
    return isinstance(value, str)

try:
    grant = verify_native_path_lease(lease, operation=OP)
except NativePathLeaseError as exc:
    if "invalid format" in str(exc):
        return error_response(400, "Malformed file grant.")
    raise

When it happens

Trigger: Passing the parsed JSON body (dict) instead of the lease field; forwarding bytes from a raw HTTP layer; a client that wraps the lease in a list/one-element array; or a truthy non-string default like 0/False coerced into an object.

Common situations: API handlers that accept the whole request object and pass it where the lease string belongs; JavaScript clients sending lease: [token] or lease: {token} via JSON; middleware that decodes the body to bytes before the route handler runs.

Related errors

• Unknown model_kind '{model_kind}'. Expected one of {sorted(_
• Linked folders support only knowledge-base and project scope
• Native path grant has the wrong path type.
• Native path grant kind is invalid.
• load error: {p.get('error')}

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