unslothai/unsloth · error · NativePathLeaseError

Native path grant operation is invalid.

Error message

Native path grant operation is invalid.

What it means

The grant's embedded operation string does not match the operation keyword passed to verify_native_path_lease(). Grants are single-purpose: a grant signed for 'import_gguf' cannot be replayed against an endpoint that verifies with operation='export_model', preventing cross-endpoint grant reuse.

Source

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

    required = (
        "version",
        "operation",
        "canonical_path",
        "path_kind",
        "path_type",
        "source_kind",
        "token_id_hash",
        "issued_at_ms",
        "expires_at_ms",
        "nonce",
    )
    missing = [key for key in required if key not in payload]
    if missing:
        raise NativePathLeaseError("Native path grant payload is missing required fields.")
    if _required_int(payload, "version") != 1:
        raise NativePathLeaseError("Native path grant version is unsupported.")
    if payload["operation"] != operation:
        raise NativePathLeaseError("Native path grant operation is invalid.")
    if expected_kind and payload["path_kind"] != expected_kind:
        raise NativePathLeaseError("Native path grant kind is invalid.")
    now_ms = int(time.time() * 1000)
    issued_at_ms = _required_int(payload, "issued_at_ms")
    expires_at_ms = _required_int(payload, "expires_at_ms")
    if issued_at_ms >= expires_at_ms:
        raise NativePathLeaseError("Native path grant timestamps are inconsistent.")
    if expires_at_ms <= now_ms:
        raise NativePathLeaseError("Native path grant has expired.")
    if issued_at_ms > now_ms + 30_000:
        raise NativePathLeaseError("Native path grant issue time is invalid.")
    for key in ("canonical_path", "nonce", "token_id_hash", "display_label"):
        raw = payload.get(key)
        if raw is None:
            continue
        if "\x00" in str(raw):
            raise NativePathLeaseError("Native path grant contains invalid characters.")

View on GitHub (pinned to 203007d190)

Solutions

  1. Request a fresh grant from the picker flow that corresponds to the target operation, and send that lease to that endpoint.
  2. Keep operation strings as shared constants (single source of truth) used by both the Rust signer invocation and the backend verifier.
  3. Namespace per-flow lease storage in the frontend so grants can't cross wires.
  4. When adding endpoints, double-check the operation literal matches what the shell signed for that dialog.

Example fix

# before
lease = await pick_file_for_import()
verify_native_path_lease(lease, operation="export_model")  # wrong purpose

# after
lease = await pick_file_for_export()
verify_native_path_lease(lease, operation="export_model")
Defensive patterns

Strategy: validation

Validate before calling

# Frontend: bind each lease to the operation it was picked for
if stored_lease.operation !== ENDPOINT_OPERATION: throw new Error('grant purpose mismatch');

Try / catch

try:
    grant = verify_native_path_lease(lease, operation=OP)
except NativePathLeaseError as exc:
    if "operation is invalid" in str(exc):
        return error_response(400, "This file selection cannot be used for that action.")
    raise

Prevention

When it happens

Trigger: Frontend reuses a lease from one flow (e.g. a file import dialog) when calling a different endpoint (e.g. export or a data-recipe upload); shared lease state across features; or a backend call site passing the wrong operation string for the endpoint's semantics.

Common situations: Refactors that rename operation identifiers on one side only; copy-pasted API wrappers sending the import lease to the export endpoint; generic 'attach file' UI funneling all leases through one handler.

Related errors

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