Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

fix(llama-prebuilt): print the correct hint for access-denied renames (WinError 5) instead of the scanner theory (#10182)

jishnav2667ce5b2867
diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index a049e2db331..5712deb22ad 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -4798,15 +4798,69 @@ def unique_install_side_path(install_dir: Path, label: str) -> Path:
return candidate
+def blocked_replace_hint(winerror: object) -> str:
+ # 5 is also what a scanner holding a handle returns (is_busy_lock_error: busy).
+ if winerror == 5:
+ return (
+ "access is denied -- a scanner or running process may still hold a handle, "
+ "or the ACLs are broken"
+ )
+ if winerror == 145:
+ return "the directory is not empty yet -- an earlier copy is still being removed"
+ return "a scanner is likely still holding the install open"
+
+
+def _tree_link_state(root: Path) -> str:
+ """Return "link", "unreadable" (root or a directory not readable) or "clean"."""
+ try:
+ root.lstat()
+ except OSError:
+ return "unreadable"
+ if _is_link_or_junction(root):
+ return "link"
+ unreadable: list[OSError] = []
+ for current_dir, dirnames, filenames in os.walk(
+ root, followlinks = False, onerror = unreadable.append
+ ):
+ current_path = type(root)(current_dir)
+ if any(_is_link_or_junction(current_path / name) for name in (*dirnames, *filenames)):
+ return "link"
+ return "unreadable" if unreadable else "clean"
+
+
+def log_acl_repair(path: Path) -> None:
+ # Printed, never run: repairing permissions is the user's call (#9928).
+ # takeown /R and icacls /T follow links, so recursion is offered only for a tree
+ # fully listed and link-free; otherwise just the root, which is not a link.
+ state = _tree_link_state(path)
+ if state == "link":
+ log(f"rename still denied after retrying; {path} contains a link, check its permissions")
+ else:
+ log(
+ "rename still denied after retrying; if the permissions on this tree are broken, run in an elevated PowerShell:"
+ )
+ recursive = state == "clean"
+ log(f'takeown /F "{path}"' + (" /R /D Y" if recursive else ""))
+ # /L: if an unreadable root is a link after all, reset the link, not its target.
+ log(f'icacls "{path}" /reset' + (" /T" if recursive else " /L"))
+ if not recursive:
+ log("then run the install again")
+ log(
+ "if access stays denied, Controlled folder access or antivirus may be blocking "
+ "the path: allow or exclude it there"
+ )
+
+
def replace_with_busy_retry(
src: Path,
dst: Path,
*,
attempts: int = 8,
+ acl_repair: bool = True,
) -> None:
"""``os.replace``, retried against transient Windows sharing violations.
- WinError 5/32/145 means a scanner still holds a handle inside the tree,
+ WinError 5/32/145 usually means a scanner holds a handle inside the tree,
which clears in a second or two; without a backoff that turns an update
into a failure, and on the aside-move of the *existing* install that is the
failure this installer most needs to avoid. Mirrors the Node installer's
@@ -4822,12 +4876,16 @@ def replace_with_busy_retry(
os.replace(src, dst)
return
except OSError as exc:
- transient = os.name == "nt" and getattr(exc, "winerror", None) in (5, 32, 145)
+ winerror = getattr(exc, "winerror", None)
+ transient = os.name == "nt" and winerror in (5, 32, 145)
if not transient or attempt == attempts - 1:
+ if acl_repair and transient and winerror == 5:
+ # src, not dst: the aside-move's dst does not exist yet.
+ log_acl_repair(src)
raise
log(
- f"rename {src.name} -> {dst.name} blocked ({exc.winerror}), retrying in "
- f"{delay:.2f}s -- a scanner is likely still holding the install open"
+ f"rename {src.name} -> {dst.name} blocked ({winerror}), retrying in "
+ f"{delay:.2f}s -- {blocked_replace_hint(winerror)}"
)
time.sleep(delay)
delay = min(delay * 2, 4.0)
@@ -5221,7 +5279,8 @@ def activate_install_tree(staging_dir: Path, install_dir: Path, host: HostInfo)
log(f"restoring rollback path {rollback_dir} -> {install_dir}")
restore_attempted = True
try:
- replace_with_busy_retry(rollback_dir, install_dir)
+ # A copy fallback follows, so ACL advice here could name a tree it then removes.
+ replace_with_busy_retry(rollback_dir, install_dir, acl_repair = False)
except OSError as restore_exc:
# The rename is the one-step restore; when it cannot run,
# the rollback tree is the sole remaining llama.cpp, so a
diff --git a/tests/studio/install/test_install_llama_prebuilt_logic.py b/tests/studio/install/test_install_llama_prebuilt_logic.py
index 35934eca860..ea7a1fae6a3 100644
--- a/tests/studio/install/test_install_llama_prebuilt_logic.py
+++ b/tests/studio/install/test_install_llama_prebuilt_logic.py
@@ -43,6 +43,7 @@ activate_install_tree = INSTALL_LLAMA_PREBUILT.activate_install_tree
activate_staged_dir = INSTALL_LLAMA_PREBUILT.activate_staged_dir
create_install_staging_dir = INSTALL_LLAMA_PREBUILT.create_install_staging_dir
replace_with_busy_retry = INSTALL_LLAMA_PREBUILT.replace_with_busy_retry
+blocked_replace_hint = INSTALL_LLAMA_PREBUILT.blocked_replace_hint
remove_tree_logged = INSTALL_LLAMA_PREBUILT.remove_tree_logged
prune_stale_install_side_paths = INSTALL_LLAMA_PREBUILT.prune_stale_install_side_paths
sha256_file = INSTALL_LLAMA_PREBUILT.sha256_file
@@ -1118,6 +1119,150 @@ def test_replace_with_busy_retry_waits_out_a_transient_windows_lock(
assert (destination / "payload.txt").read_text() == "payload\n"
+def test_blocked_replace_hint_names_the_cause_per_winerror():
+ assert "scanner" in blocked_replace_hint(32)
+ denied = blocked_replace_hint(5)
+ assert "access is denied" in denied and "ACL" in denied
+ not_empty = blocked_replace_hint(145)
+ assert "not empty" in not_empty and "scanner" not in not_empty
+
+
+def _run_denied_replace(tmp_path, monkeypatch, failures):
+ source = tmp_path / "src"
+ source.mkdir()
+ (source / "payload.txt").write_text("payload\n")
+ destination = tmp_path / "dst"
+ original_replace = INSTALL_LLAMA_PREBUILT.os.replace
+ attempts = {"count": 0}
+
+ def access_denied(src, dst):
+ attempts["count"] += 1
+ if attempts["count"] <= failures:
+ exc = OSError(errno.EACCES, "Access is denied")
+ exc.winerror = 5
+ raise exc
+ return original_replace(src, dst)
+
+ logged: list[str] = []
+ monkeypatch.setattr(INSTALL_LLAMA_PREBUILT.os, "name", "nt")
+ monkeypatch.setattr(INSTALL_LLAMA_PREBUILT.os, "replace", access_denied)
+ monkeypatch.setattr(INSTALL_LLAMA_PREBUILT.time, "sleep", lambda _seconds: None)
+ monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "log", logged.append)
+ return source, destination, logged
+
+
+def test_replace_with_busy_retry_prints_acl_repair_once_when_denial_persists(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+):
+ source, destination, logged = _run_denied_replace(tmp_path, monkeypatch, failures = 99)
+ with pytest.raises(OSError):
+ replace_with_busy_retry(source, destination, attempts = 3)
+ retry_lines = [line for line in logged if "blocked (5)" in line]
+ assert len(retry_lines) == 2 and "scanner" not in retry_lines[0].split("--")[0]
+ assert all("takeown" not in line for line in retry_lines)
+ # One command per line so each can be pasted; src is the tree, dst does not exist yet.
+ assert logged.count(f'takeown /F "{source}" /R /D Y') == 1
+ assert logged.count(f'icacls "{source}" /reset /T') == 1
+ assert not any(str(destination) in line for line in logged if "takeown" in line)
+ assert any("Controlled folder access" in line for line in logged)
+
+
+def test_replace_with_busy_retry_offers_no_recursive_repair_for_a_linked_tree(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+):
+ target = tmp_path / "external"
+ target.mkdir()
+ link = tmp_path / "linked"
+ try:
+ link.symlink_to(target, target_is_directory = True)
+ except OSError as exc:
+ pytest.skip(f"directory symlinks unavailable: {exc}")
+ _source, destination, logged = _run_denied_replace(tmp_path, monkeypatch, failures = 99)
+ # os.name is spoofed to "nt", so the real probe would look for Windows reparse attributes.
+ monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "_is_link_or_junction", lambda p: p == link)
+ with pytest.raises(OSError):
+ replace_with_busy_retry(link, destination, attempts = 2)
+ assert not any("takeown" in line or "icacls" in line for line in logged)
+ assert any("contains a link" in line for line in logged)
+
+
+def test_replace_with_busy_retry_offers_no_recursive_repair_over_a_nested_link(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+):
+ outside = tmp_path / "outside"
+ outside.mkdir()
+ source, destination, logged = _run_denied_replace(tmp_path, monkeypatch, failures = 99)
+ try:
+ (source / "link-out").symlink_to(outside, target_is_directory = True)
+ except OSError as exc:
+ pytest.skip(f"directory symlinks unavailable: {exc}")
+ monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "_is_link_or_junction", lambda p: p.is_symlink())
+ with pytest.raises(OSError):
+ replace_with_busy_retry(source, destination, attempts = 2)
+ assert not any("takeown" in line or "icacls" in line for line in logged)
+
+
+def test_replace_with_busy_retry_offers_only_a_root_repair_for_an_unlistable_tree(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+):
+ source, destination, logged = _run_denied_replace(tmp_path, monkeypatch, failures = 99)
+
+ def denied_walk(
+ top,
+ onerror = None,
+ **_kwargs,
+ ):
+ onerror(PermissionError(errno.EACCES, "Access is denied", str(top)))
+ return iter(())
+
+ monkeypatch.setattr(INSTALL_LLAMA_PREBUILT, "_is_link_or_junction", lambda p: False)
+ monkeypatch.setattr(INSTALL_LLAMA_PREBUILT.os, "walk", denied_walk)
+ with pytest.raises(OSError):
+ replace_with_busy_retry(source, destination, attempts = 2)
+ assert f'takeown /F "{source}"' in logged
+ assert f'icacls "{source}" /reset /L' in logged
+ assert not any(
+ "/R" in line or "/T" in line for line in logged if "takeown" in line or "icacls" in line
+ )
+
+
+def test_replace_with_busy_retry_offers_a_root_repair_when_the_root_cannot_be_read(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+):
+ source, destination, logged = _run_denied_replace(tmp_path, monkeypatch, failures = 99)
+ real_lstat = type(source).lstat
+
+ def denied_lstat(self):
+ if self == source:
+ raise PermissionError(errno.EACCES, "Access is denied")
+ return real_lstat(self)
+
+ monkeypatch.setattr(type(source), "lstat", denied_lstat)
+ with pytest.raises(OSError):
+ replace_with_busy_retry(source, destination, attempts = 2)
+ assert f'takeown /F "{source}"' in logged
+ assert not any("contains a link" in line for line in logged)
+
+
+def test_replace_with_busy_retry_can_withhold_the_acl_repair(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+):
+ source, destination, logged = _run_denied_replace(tmp_path, monkeypatch, failures = 99)
+ with pytest.raises(OSError):
+ replace_with_busy_retry(source, destination, attempts = 2, acl_repair = False)
+ assert not any("takeown" in line or "icacls" in line for line in logged)
+
+
+def test_replace_with_busy_retry_skips_acl_repair_when_denial_clears(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+):
+ source, destination, logged = _run_denied_replace(tmp_path, monkeypatch, failures = 1)
+ replace_with_busy_retry(source, destination)
+ assert (destination / "payload.txt").read_text() == "payload\n"
+ assert any("blocked (5)" in line for line in logged)
+ assert not any("takeown" in line for line in logged)
+
+
def test_replace_with_busy_retry_does_not_retry_a_posix_permission_error(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
):