unslothai/unsloth · error · NativePathLeaseError

Native path grants require the managed desktop backend.

Error message

Native path grants require the managed desktop backend.

What it means

The lease-signing secret is absent: neither the UNSLOTH_STUDIO_NATIVE_PATH_LEASE_SECRET environment variable nor the temporarily scrubbed copy (_SCRUB_SAVED_SECRET) is set. That secret is installed only by the managed Tauri desktop launcher, so its absence means the process is not running under the managed desktop backend.

Source

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

        for variant in {path, path.replace("/", "\\"), path.replace("\\", "/")}:
            if variant:
                redacted = redacted.replace(variant, "<native_path>")
    return redacted


def _decode_secret() -> bytes:
    global _CACHED_LEASE_SECRET
    if _CACHED_LEASE_SECRET is not None:
        return _CACHED_LEASE_SECRET
    with _SECRET_INIT_LOCK:
        if _CACHED_LEASE_SECRET is not None:
            return _CACHED_LEASE_SECRET
        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(".")

View on GitHub (pinned to 203007d190)

Solutions

1. If you need lease support, run the backend under the managed Tauri desktop app so it injects the secret.
2. Use native_path_leases_supported() to feature-detect and disable native-path flows (fall back to regular uploads) when the secret is absent.
3. If a child worker needs to verify leases, pass the verified NativePathGrant (or the resolved path result) from the parent instead of re-verifying inside a worker that had the secret scrubbed.
4. For dev/test, set UNSLOTH_STUDIO_NATIVE_PATH_LEASE_SECRET to a base64url-encoded >=32-byte random value matching your signing harness.

Example fix

# before
grant = verify_native_path_lease(lease, operation="read")  # raises in child workers

# after
if not native_path_leases_supported():
    raise UnsupportedEnvironmentError("Native file access needs the managed desktop backend.")
grant = verify_native_path_lease(lease, operation="read")

from utils.native_path_leases import native_path_leases_supported

if not native_path_leases_supported():
    return error_response(501, "Native file access requires the managed desktop app.")

native_path_leases_supported  # built-in feature check; returns False instead of raising

try:
    grant = verify_native_path_lease(lease, operation=OP)
except NativePathLeaseError as exc:
    if "require the managed desktop backend" in str(exc):
        return error_response(501, "Run inside the desktop app to use native file access.")
    raise

When it happens

Trigger: Starting the studio backend manually (python -m, uvicorn, pytest) outside the Tauri shell; a child process spawned via run_without_native_path_secret() (which deliberately deletes the env var) later attempting lease verification; the env var name misspelled or stripped by a supervisor/unit file; or the secret scrub window (native_path_secret_removed_for_child_start) covering the verification call.

Common situations: Local dev servers, CI test runs, Docker deployments, or multiprocessing workers where the desktop launcher never ran; systemd/launchd configs that whitelist specific env vars; or code that spawns inference/training workers via run_without_native_path_secret and those workers try to re-verify a lease forwarded from the parent.

Related errors

• The executable at {binary} is not stable-diffusion.cpp: its
• UNSLOTH_CPU_THREADS must be a positive integer
• Native path grant is required.
• Native path grant secret is invalid.
• Add a Provider connection block before running this recipe.

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