unslothai/unsloth · error · ValueError

The linked-folder scope no longer exists

Error message

The linked-folder scope no longer exists

What it means

Raised inside create_folder's BEGIN IMMEDIATE transaction when the target scope appears in the linked_folder_retired_scopes table. That tombstone table records scopes (knowledge bases/projects) that were deleted; new linked folders may not be attached to a deleted scope, keeping referential integrity without FK enforcement across stores.

Source

Thrown at studio/backend/core/rag/folder_sync.py:247

    except RuntimeError as exc:
        raise ValueError(str(exc)) from exc
    if expected_identity is not None and (root_device, root_inode) != expected_identity:
        raise ValueError("Linked folder changed after it was selected")
    scope = (
        store.kb_scope(scope_id)
        if scope_type == "knowledge_base"
        else store.project_scope(scope_id)
    )
    folder_id = str(uuid.uuid4())
    now = _now()
    with _scope_lock(scope):
        conn = rag_db.get_connection()
        try:
            conn.execute("BEGIN IMMEDIATE")
            if conn.execute(
                "SELECT 1 FROM linked_folder_retired_scopes WHERE scope=?", (scope,)
            ).fetchone():
                raise ValueError("The linked-folder scope no longer exists")
            normalized_key = _path_key(normalized)
            existing = conn.execute(
                "SELECT * FROM linked_folders WHERE scope=?", (scope,)
            ).fetchall()
            for row in existing:
                existing_key = _path_key(row["path"])
                if existing_key == normalized_key or _same_file(row["path"], normalized):
                    if row["status"] == "retired" or row["delete_remove_index"] is not None:
                        raise ValueError("Linked folder is still being removed")
                    conn.rollback()
                    return _reauthorize_folder(row["id"], normalized, expected_identity)
                if _paths_overlap(existing_key, normalized_key):
                    raise ValueError("Linked folders in the same scope cannot overlap")
            try:
                current_identity = _root_identity(normalized)
            except RuntimeError as exc:
                raise ValueError(str(exc)) from exc
            if current_identity != (root_device, root_inode) or (

View on GitHub (pinned to 203007d190)

Solutions

  1. Have the caller verify the knowledge base/project still exists (store.kb_scope/store.project_scope) and refresh UI state before retrying.
  2. Discard the request: the scope is deleted, linking folders to it is invalid by design.
  3. If the scope was recreated with the same id, clear the retired-scopes tombstone as part of scope re-creation logic (or recreate with a new id).
Defensive patterns

Strategy: validation

Validate before calling

# Best-effort pre-check; the authoritative check is the tombstone table itself.
def scope_is_live(scope_type: str, scope_id: str) -> bool:
    try:
        (store.kb_scope(scope_id) if scope_type == "knowledge_base"
         else store.project_scope(scope_id))
        return True
    except Exception:
        return False

Try / catch

try:
    create_folder(...)
except ValueError as e:
    if "scope no longer exists" in str(e):
        refresh_ui_scope_state(scope_id)  # scope was deleted; drop the request
    else:
        raise

Prevention

When it happens

Trigger: create_folder for a knowledge_base or project whose deletion ran concurrently or earlier and wrote a retirement row: a race between 'create KB -> add folder' and 'delete KB' on different threads, or a retry of an old request after the user deleted the KB/project in the UI.

Common situations: UI optimistic add racing a delete; queued background job re-registering a folder for a scope the user already removed; stale client tab submitting after project deletion.

Related errors

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