unslothai/unsloth · error · HTTPException

Native folder grant has no stable identity.

Error message

Native folder grant has no stable identity.

What it means

When linking a native folder, the verified lease grant must carry a stable identity (device_id and file_id — dev/inode pair) so later syncs can detect folder replacement. If either attribute is None on the grant, NativePathLeaseError('Native folder grant has no stable identity.') is raised and mapped to HTTP 400. This guards against network filesystems or FUSE mounts where stat identity is not stable.

Source

Thrown at studio/backend/routes/rag.py:293

    verify = verifier or verify_native_path_lease
    try:
        grant = verify(
            native_path_lease,
            operation = "link-documents",
            expected_kind = "document-folder",
            expected_path_type = "directory",
        )
        device_id = getattr(grant, "device_id", None)
        file_id = getattr(grant, "file_id", None)
        if device_id is None or file_id is None:
            raise NativePathLeaseError("Native folder grant has no stable identity.")
        return (
            folder_sync.validate_folder_path(str(grant.canonical_path)),
            (device_id, file_id),
        )
    except NativePathLeaseError as exc:
        raise HTTPException(status_code = 400, detail = str(exc)) from exc
    except ValueError as exc:
        raise HTTPException(status_code = 400, detail = str(exc)) from exc


def _folder_view(row: dict) -> dict:
    status = (
        "syncing"
        if row["status"] == "syncing"
        else "error"
        if row["status"] in {"error", "retired"}
        else "idle"
    )
    return {
        "id": row["id"],
        "displayName": row["name"],
        "scopeType": row["scope_type"],
        "scopeId": row["scope_id"],
        "status": status,

View on GitHub (pinned to 203007d190)

Solutions

1. Choose a folder on the local physical filesystem (stable device/inode) rather than a network or FUSE mount.
2. Update the desktop bridge / lease issuer so grants include device_id and file_id.
3. If a network folder must be used, copy it to local storage and link the local copy.

import os
st = os.stat(folder)
# leases need stable dev/inode; network mounts often report 0 or per-mount values
if st.st_dev == 0:
    warn('folder identity unstable; choose a local filesystem folder')

if (res.status === 400 && detail.includes('stable identity')) { suggestLocalFolder(); }

When it happens

Trigger: Requesting a linked-folder sync with a lease whose grant object lacks device_id/file_id — typically a path on NFS, SMB, or a FUSE/virtual filesystem that does not provide stable dev/inode values, or a lease issued by an older bridge version that omitted the fields.

Common situations: User tries to link a folder on a network share, cloud-drive mount (rclone, Dropbox daemon), or container volume with unstable inode semantics; desktop-bridge version skew where grants were created without identity fields.

Related errors

• Native path grant is required.
• Dropped file could not be read.
• Path cannot be empty
• Linked folders support only knowledge-base and project scope
• Unsupported file type '{ext}'. Allowed: {sorted(config.UPLOA

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