unslothai/unsloth · error · NativePathLeaseError

Native path grant is required.

Error message

Native path grant is required.

What it means

verify_native_path_lease() was called with a falsy lease value (None or empty string). The backend requires a signed native path grant (issued by the Tauri/Rust desktop shell) before it will touch any user-selected filesystem path; a missing grant means the request never went through the managed file-picker flow.

Source

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

        try:
            yield
        finally:
            _SCRUB_REFCOUNT -= 1
            if _SCRUB_REFCOUNT == 0 and _SCRUB_SAVED_SECRET is not None:
                os.environ[LEASE_SECRET_ENV] = _SCRUB_SAVED_SECRET
                _SCRUB_SAVED_SECRET = None


def verify_native_path_lease(
    lease: str | None,
    *,
    operation: str,
    expected_kind: str | None = None,
    expected_path_type: str | None = None,
    allowed_suffixes: Iterable[str] | None = None,
) -> NativePathGrant:
    if not lease:
        raise NativePathLeaseError("Native path grant is required.")

    secret = _decode_secret()
    payload_b64, signature_b64 = _split_lease(lease)
    expected_signature = hmac.new(
        secret,
        payload_b64.encode("ascii"),
        hashlib.sha256,
    ).digest()
    supplied_signature = _b64decode(signature_b64)
    if not hmac.compare_digest(expected_signature, supplied_signature):
        raise NativePathLeaseError("Native path grant signature is invalid.")

    payload = _decode_payload(payload_b64)
    _validate_payload(payload, operation = operation, expected_kind = expected_kind)

    path = Path(str(payload["canonical_path"]))
    _reject_network_or_device_path(path)
    try:

View on GitHub (pinned to 203007d190)

Solutions

1. Ensure the desktop file-picker flow completes and its returned grant string is forwarded verbatim as the lease argument.
2. Check the frontend state/serialization: confirm the lease field is present, non-empty, and not renamed between the dialog callback and the API call.
3. If you are calling the endpoint from tests or a non-desktop context, obtain a lease from the Tauri shell or mock verify_native_path_lease instead of passing None.
4. Guard the call with native_path_leases_supported() and show a 'managed desktop backend required' message when it returns False.

Example fix

// before
result = import_native_gguf(path=selected_path, lease=None)

# after
if not lease:
    raise ValueError("Select a file in the desktop dialog first; it returns the required grant.")
result = import_native_gguf(path=selected_path, lease=lease)

def require_lease(lease):
    if not isinstance(lease, str) or not lease.strip():
        raise HTTPBadRequest("Native path grant is required; re-select the file in the desktop dialog.")
    return lease

def is_lease_string(value: object) -> bool:
    return isinstance(value, str) and len(value) > 0

try:
    grant = verify_native_path_lease(lease, operation=OP)
except NativePathLeaseError as exc:
    if "grant is required" in str(exc):
        return error_response(400, "Please select a file first.")
    raise

When it happens

Trigger: Any backend API that accepts a nativePathLease parameter being called with lease=None, lease omitted from the request payload, or an empty string — e.g. a frontend form that submitted before the desktop dialog returned a grant, a test/CI harness calling the endpoint directly, or a client that dropped the lease field during serialization.

Common situations: Running the studio backend outside the Tauri desktop app (no grant issuance possible), frontend code that reads the grant from state before the native dialog resolves, JSON payloads where the lease key is misspelled, or replaying a captured request without the lease header/field.

Related errors

• Native path grant has the wrong path type.
• Native path grant has an unsupported file type.
• Native path grants require the managed desktop backend.
• Native path grant kind is invalid.
• Native path grant timestamps are inconsistent.

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