Self-update (auto-update on startup and `kbagent update`) can corrupt the uv tool venv on Windows — non-atomic in-place upgrade of the running venv

[papousek-radan]

Summary

kbagent's self-update mechanism — both the automatic Updating kbagent vX -> vY... on startup and the explicit kbagent update — can leave the uv tool venv in a corrupted, inconsistent state on Windows. The update swaps packages in-place inside the venv the running kbagent.exe was launched from, so any mid-flight failure (network error, locked file) strands the venv between versions and every subsequent invocation crashes.

Observed twice in two days on the same machine.

Environment

• Windows 11 Enterprise (10.0.26200)
• kbagent installed via uv tool install "keboola-cli[server] @ <release wheel URL>", Python 3.14
• kbagent versions involved: 0.72.0 → 0.75.0 (incident 1), 0.75.0 → 0.76.1 (incident 2)

Incident 1 — auto-update on startup (2026-07-22, 0.72.0 → 0.75.0)

On startup kbagent printed Updating kbagent v0.72.0 -> 0.75.0..., the update failed but kbagent continued. Afterwards the venv had mismatched rich/typer versions, and every subsequent invocation failed with:

ModuleNotFoundError: No module named 'rich._windows'

and

ImportError: cannot import name 'rich_utils' from 'typer'

Incident 2 — explicit kbagent update (2026-07-23, 0.75.0 → 0.76.1)

kbagent update crashed mid-update:

version_service.self_update → _update_mcp → httpx create_ssl_context → FileNotFoundError

The FileNotFoundError was for certifi's CA bundle file — the old dist had already been partially removed from site-packages while the still-running process referenced it, so when the post-update MCP version check tried to create an SSL context, certifi's cacert.pem no longer existed on disk. The venv was left broken between versions.

Root cause (as far as we can tell)

The self-update replaces site-packages / the entrypoint in-place, inside the venv that the running kbagent.exe was launched from:

• On Windows the running exe is locked, so the upgrade fails with os error 32 if e.g. kbagent serve is running (that part is expected and correctly reported).
• But even without an exe lock, the dependency swap is not atomic. If anything fails mid-flight — a network error in the MCP-update step, a locked file — the venv is stranded with a mix of old and new dists, and there is no rollback.
• Incident 2 shows the ordering problem specifically: files were being removed/replaced before the network-dependent MCP latest-version check ran, so a failure in that check left the swap half-done.

Recovery that works

uv tool install --force "keboola-cli[server] @ <release wheel URL>"

fully rebuilds the venv and fixes both incidents.

Suggested fixes

1. Perform self-update via uv tool install --force (or equivalent) into a fresh resolution rather than an in-place pip-style upgrade of the live venv — a failure then leaves the old install untouched.
2. Alternatively, spawn a detached updater process that runs after the CLI exits, so the update never mutates the venv of a running process.
3. Independently of 1/2: fetch the MCP-server latest-version check (and any other network calls) before touching any files, so a network failure can't interrupt the swap.

Context

Same reporter/setup as #522 (the cp1250 kbagent serve startup crash, fixed in #526 / v0.76.1) — happy to provide more logs or test a fix.

[padak]

Thank you again for the detailed report and the concrete certifi / rich
failure examples — they made the unsafe update sequence much easier to pin
down.

The fix is now released in
v0.76.2. Self-update
now completes all discovery and network checks before mutation, updates the
independent MCP environment first, then performs an exact-version full
kbagent reinstall as the terminal step and immediately re-executes. A failed
or timed-out reinstall also prints a copy-paste recovery command.

Could you please try the update again on the same Windows setup and let us
know whether it now completes cleanly without the certifi / rich
breakage?

And I promise: I’ll get a Windows machine for regular testing so we can catch
this class of problem earlier. Thank you for helping us make the Windows
experience better!

[papousek-radan]

Thanks for the quick turnaround! Tested today on the same Windows 11 machine (Python 3.14, uv tool install).

One caveat on methodology: since the machine was still on 0.76.1, running kbagent update from there would have executed the old (unsafe) updater for the 0.76.1 → 0.76.2 jump. We didn't want to risk stranding the venv again, so we moved to 0.76.2 via the recovery path instead:

uv tool install --force "keboola-cli[server] @ https://github.com/keboola/cli/releases/download/v0.76.2/keboola_cli-0.76.2-py3-none-any.whl"

Results on 0.76.2:

• Clean install, all 52 packages resolved consistently — no rich/typer mismatch, certifi intact (rich==15.0.0, typer==0.27.0, certifi==2026.7.22).
• kbagent --version → kbagent v0.76.2, kbagent doctor → 10 checks, 7 passed, 2 pre-existing cosmetic warnings (the 0o666 config permissions on Windows and unset KBAGENT_CONVERSATION_ID), nothing update-related.
• kbagent update running under 0.76.2 correctly reports kbagent v0.76.2 (already up to date) | keboola-mcp-server v1.73.2 (already up to date) and touches nothing.

So the new updater's no-op path works and the venv is healthy. The full end-to-end test of the new sequence (an actual version jump with network-checks-first → MCP-first → exact-version reinstall → re-exec) will naturally happen at the next release — we'll let the auto-update run then and report back here if anything breaks on this machine.

Tiny unrelated note from the install log: warning: The package typer==0.27.0 does not have an extra named 'all' — looks like the dependency spec still says typer[all], which recent typer versions no longer define. Harmless, but easy to drop.

And thank you for getting a Windows machine into the test loop — much appreciated!

— Radan's Claude 🤖 (posted on behalf of @papousek-radan)

[padak]

Thank you again for the careful methodology and for not risking the old 0.76.1 updater — that distinction is exactly right. The healthy recovery install and the successful 0.76.2 no-op update give us useful partial confirmation.

We'll keep this issue open until the next release provides a real 0.76.2 → newer-version jump. We'd be very grateful if you let that auto-update run and report back.

Thank you also for spotting the Typer warning. You were right: our direct dependency still requested the removed all extra. I've opened #534 to remove it without changing the version floor or dependency graph.

Thanks again for such thorough Windows testing!