Bugs caught during WSL → Debian 13 migration (2026-04-22)

Synced read-only from /home/synnet/mirrors/synvirt-product/docs/MIGRATION_FINDINGS.md. Edit at the source, not here.

Bugs caught during WSL → Debian 13 migration (2026-04-22)

Four latent bugs surfaced when running scripts/debian-bootstrap.sh followed by cargo build --release and iso-builder/build.sh on a clean Debian 13 VMware VM (no state inherited from the prior WSL host). All were pre-existing; the migration only exposed them because host environment assumptions and pre-populated vendor caches were gone.

1. libclang-dev / llvm-dev missing from bootstrap

• Symptom: cargo build --release failed with clang-sys v1.8.1 build script panicking: couldn't find any valid shared libraries matching: ['libclang.so', 'libclang-*.so'].
• Root cause: scripts/debian-bootstrap.sh installed clang llvm but not libclang-dev / llvm-dev. A transitive bindgen user in the workspace (via clang-sys) needs libclang.so at build time, which only ships with the -dev packages.
• Fix: scripts/debian-bootstrap.sh:69 — appended libclang-dev llvm-dev to the base-tooling apt install.
• Pre-existing / new: pre-existing latent. The old WSL host happened to have libclang-dev installed manually at some point.

2. cargo not in PATH under sudo / root in iso-builder/build.sh

• Symptom: sudo ./build.sh failed immediately at step [1/6] with cargo: command not found (exit 127).
• Root cause: rustup installs cargo under the invoking user’s ~/.cargo/bin. sudo enforces secure_path, which does not include user cargo dirs. build.sh assumed cargo was reachable.
• Fix: iso-builder/build.sh:19-38 — guard block that sources ${SUDO_USER}/.cargo/env, /home/synvirt/.cargo/env, or ${HOME}/.cargo/env in that order before running any cargo command; exits 127 with a clear error if none succeed.
• Pre-existing / new: pre-existing latent. Old workflow ran ./build.sh as the user (sudo only for lb build internals), so the top-level invocation always had cargo in PATH.

3. virtio-win URL filename mismatch in build.sh

• Symptom: [3/6] building guest-tools ISO died with curl: (22) The requested URL returned error: 404 on .../archive-virtio/virtio-win-0.1.240-1/virtio-win-0.1.240-1.iso.
• Root cause: upstream convention is a dir with -N suffix but the ISO inside has no -N, e.g. virtio-win-0.1.240-1/virtio-win-0.1.240.iso. build.sh interpolated the same VIRTIO_WIN_VERSION into both, so the constructed URL never existed at any version (verified against 0.1.240-1 through 0.1.285-1).
• Fix: iso-builder/build.sh:80-86 — split into VIRTIO_WIN_VERSION (numeric part, default 0.1.240) and VIRTIO_WIN_DIR_SUFFIX (default -1). The filename uses only the version; the dir concatenates both. Smoke-tested: HTTP 200 on the patched URL.
• Pre-existing / new: pre-existing latent. Never caught because iso-builder/vendor/guest-tools/ was pre-populated on old hosts (finding #4), so the curl path was skipped.

4. iso-builder/vendor/guest-tools/ relied on inherited host state

• Symptom: the guest-tools fetch path in build.sh was never exercised on previously-used dev hosts. Clean migration had an empty vendor/guest-tools/, so the broken URL from finding #3 executed for the first time.
• Root cause: the cache dir is (correctly) gitignored, but there is no documented pre-fetch step for fresh hosts, nor a checksum manifest. New operators discover the path only when it fails.
• Fix: none in tree — addressed indirectly by fix #3 (fresh fetch now succeeds on first run). Documentation of the flag SYNVIRT_SKIP_GUEST_TOOLS=1 remains the escape hatch.
• Pre-existing / new: pre-existing, architectural. Worth revisiting if a CI runner or second dev host ever enters the rotation.