nix-config-ryan4yin/WORKAROUNDS.md

Workarounds & known gaps

Temporary workarounds, version pins, carried patches, and known gaps are collected here, grouped by type, each with the condition under which it can be removed. Review the list periodically so obsolete workarounds get rolled back instead of lingering.

How to use

• Adding — a change that introduces a workaround, pin, carried patch, or known gap adds a row under the matching section below in the same PR, with a concrete removal condition.
• Removing — once the removal condition is met, delete the change and set Status to removed (mention the ID in the commit), or delete the row.
• Reviewing — re-evaluate rows whose Revisit trigger is due and refresh Status.

Pins

A version or revision pinned for a reason that can go away.

ID	What & where	Why	Removal condition	Added	Revisit	Status
WA-001	smartctl_exporter pinned to upstream 6274decc, which carries PR #329 — overlays/smartctl-exporter/	/metrics returns HTTP 500 once a device becomes readable after startup (#305, #326)	Drop once nixpkgs provides a version containing the #329 fix	2026-10-03	next nixpkgs bump	active
WA-002	nixpkgs-2505 — flake.nix; consumer home/base/tui/container.nix	kubernetes-helm regressed in newer nixpkgs	Drop the input and its consumer once helm works again in current nixpkgs	2025-12-03	when helm is revisited	active
WA-003	rust-overlay follow — flake.nix	lanzaboote v1.1.0's pinned rust-overlay uses the deprecated stdenv.isLinux/stdenv.isDarwin	Drop the follow once lanzaboote updates its pin (or we drop the lanzaboote pin)	2026-09-25	on lanzaboote bump	active
WA-004	catppuccin on main — flake.nix	main carries the nodejs→nodejs-slim deprecation fix, which is not in a release	Switch to a release tag once it includes the fix	2026-09-25	on catppuccin release	active
WA-005	tuios input — flake.nix; home/base/tui/tuios/	nixpkgs lags behind upstream	Use nixpkgs' tuios once it is recent enough	2026-10-03	on nixpkgs bump	active
WA-006	nixpkgs-blender — flake.nix	Blender 5.2 LTS + CUDA/OptiX pin; keeps just up from triggering a full source rebuild	Bump deliberately when needed; drop the pin if the current nixpkgs build is acceptable	2026-07-24	deliberate	active
WA-007	WeChat from nixpkgs-master — hardening/bwraps/default.nix	newest builds; the pinned channel lags	Fall back to the stable channel once it has a good build	2026-10-03	on nixpkgs bump	active
WA-020	fcitx5-vinput pinned to release tag v2.4.0 — flake.nix; consumer home/linux/gui/base/vinput/default.nix	Tracks a release tag instead of a branch, so just up stays on that release	Bump to a newer release tag when its changes are wanted	2026-10-04	on vinput release	active
WA-021	nix-x86-on-aarch64 input — our fork of rowanG077's patched FEX + muvm runtime — flake.nix; hosts/12kingdoms-shoukei/game/	FEX does not support 16K pages, so x86/x86_64 apps and games on shoukei need this pinned flake's 4K-page microVM runtime; our fork lets upstream changes be reviewed before use	Drop once FEX supports 16K pages directly, or nixpkgs/nixos-apple-silicon ships an equivalent runtime	2026-10-07	on FEX/nixpkgs/muvm update	active
WA-023	nix.package = pkgs.nixVersions.latest — modules/nixos/base/nix.nix	NixOS is opted into Nix 2.35 (2.35.2), which nixpkgs ships as nixVersions.latest, while nixVersions.stable is still 2.34	Drop the override and fall back to the default pkgs.nix once nixVersions.stable is 2.35 or newer	2026-10-07	next nixpkgs bump	active

Workarounds

A setting that works around a bug or a hardware quirk.

ID	What & where	Why	Removal condition	Added	Revisit	Status
WA-008	Relaxed NVMe APST (nvme_core.default_ps_max_latency_us=100000) — hosts/idols-ai/hardware-configuration.nix, hosts/idols-aquamarine/hardware-configuration.nix	the KINGBANK KP260 (DRAM-less QLC) froze on slow APST wake-ups	Drop the override once kernel/firmware fixes or replacement hardware make default APST reliable	2026-10-03	watch NVMe timeout/reset/AER in the journal	active
WA-009	USB-SATA bridge mitigations (usbcore.autosuspend=-1, usb-storage.delay_use=10) — hosts/12kingdoms-youko/default.nix	flaky JMicron JMS567 resets with UDMA-CRC and I/O errors	Drop once the bridge/controller is replaced; the signal is smartctl CRC/media errors	2026-09-21	on hardware change or CRC errors	active
WA-010	Insta360 Link USB reset on S3 resume — hosts/idols-ai/default.nix	the camera stays enumerated with a stalled UVC endpoint after resume	Drop after the Insta360 firmware or the kernel uvcvideo fixes it	2026-08-01	on kernel or firmware change	active
WA-011	Kernel module blacklist (esp4, esp6, rxrpc) — hardening/kernel-hardening.nix	attack surface for the Dirty Frag LPE (CVE-2026-43284 / CVE-2026-43500)	Kept as defence in depth; drop only if something needs those modules	2026-10-03	rarely	active
WA-017	keyd right-hand modifier passthrough — modules/nixos/desktop/peripherals.nix	keyd folds right Ctrl/Shift/Meta into their left keys	Drop once keyd or fcitx5 keeps right-hand modifiers distinct	2026-10-05	on keyd bump	active
WA-018	user-owned ~/.ssh/config + disabled systemd ssh-proxy include — home/base/tui/ssh.nix, modules/nixos/base/ssh.nix	bwrap exposes root-owned store files as nobody	Drop once sandboxes preserve store ownership	2026-10-06	when sandbox layout changes	active
WA-019	programs.steam.extraCompatPackages = [ pkgs.dwproton-bin pkgs.proton-ge-bin ] — modules/nixos/desktop/gaming.nix	ACE games fail on GE/mainline Proton, work with DW-Proton	Drop once mainline or GE-Proton runs these games (GE-Proton#433)	2026-10-07	on Proton/GE bump	active
WA-024	Wi-Fi power saving disabled (networking.networkmanager.wifi.powersave = false) — hosts/12kingdoms-shoukei/apple-silicon.nix	On this BCM4378/brcmfmac laptop, powersave is a common source of intermittent ASSOC-REJECT / authentication-timeout failures; NetworkManager then mistakes the failure for a bad key, re-prompts, and the client (Noctalia, nmtui, nmcli) saves the answer as a duplicate <SSID> 1 profile	Drop once the kernel carries the brcmfmac port_authorized fix (WA-025) and no association failures remain	2026-10-07	watch journalctl -u wpa_supplicant for ASSOC-REJECT / authentication timeout	active
WA-026	guest deploys run installOnHost then systemctl restart microvm@<guest> on the physical host — Justfile, lib/genMicrovmGuestModule.nix	the sshSwitch step runs nix-store --load-db against the guest's read-only virtiofs /nix/store and dies on cannot remount "/nix/store" writable (nix 2.35)	Drop the manual path once microvm.nix or nix handles a read-only store switch. A host activation re-links /var/lib/microvms/<guest>/current to the runner baked into the host's system, so switch the host after installing a guest from a newer tree	2026-10-09	on microvm.nix or nix bump	active
WA-028	GitHub SSH pinned to IPv4 (AddressFamily = "inet") — home/base/tui/ssh.nix	a v6 fake AAAA for ssh.github.com from the 2001:2::/64 pool (WA-029) is not proven on the 443 SSH tunnel yet	Drop once the v6 fake-ip pool is proven for GitHub SSH	2026-10-10	on a mihomo bump or a v6 pool change	active
WA-029	mihomo fake-ip-range6 is 2001:2::/64, not the shipped ULA default — modules/nixos/desktop/networking/mihomo/generate.nu	the default fdfe:dcba:9876::/64 sits in fc00::/7, which Local Network Access calls local, so a public page loaded over the v4 fake pool and pulling a dual-stack subresource prompts for local-network access (Chrome 154, Firefox). The same range also stalled ssh: a session to a fake AAAA authenticated and then never closed, on both gvisor and mips. 2001:2::/48 is RFC 5180 benchmarking -- the v6 twin of the 198.18.0.0/15 v4 default, absent from that table -- and both symptoms went with the move	Go back to the upstream default once mihomo ships a pool outside the LNA non-public table; the ULA default brings the ssh stall back	2026-10-09	on a browser or mihomo bump -- that table already grew to cover 2001:db8::/32 and 198.18.0.0/15	active
WA-030	mihomo unit sets SKIP_SYSTEM_IPV6_CHECK=1 — modules/nixos/desktop/networking/mihomo/default.nix	mihomo checks at startup whether another NIC already holds an IPv6 address and, finding none, skips the TUN's v6 half -- but strict-route still installs its v6 blackhole (ip -6 rule add priority 9000 unreachable). On a cold boot that rule lands before networkd's Router Solicitation is answered, so the host can never send RS/NS, never gets a GUA, and mihomo never re-checks: self-locking until the core restarts. The env var forces the TUN v6 address up, which installs mihomo's normal v6 rules whose lookup main suppress_prefixlength 0 keeps on-link neighbor discovery and the RA default route off the TUN	Drop once mihomo either re-runs the IPv6 check or skips the v6 strict-route blackhole when the v6 TUN is disabled	2026-10-10	on a mihomo bump	active
WA-031	iommu=pt kernel parameter — hosts/idols-aquamarine/hardware-amd-gpu.nix	ROCm's system requirements warn that multi-GPU systems may need IOMMU passthrough to prevent application hangs, and this host has two Radeon AI PRO R9700 cards. Added before the first inference run; not yet observed on gfx1201.	Drop once a ROCm release states that the default IOMMU mode is safe for multi-GPU gfx1201, or when the host runs a single GPU	2026-10-13	on a ROCm bump, or on the first hang report	active
WA-032	amdgpu.runpm=0 kernel parameter — hosts/idols-aquamarine/hardware-amd-gpu.nix	this board's DSDT advertises ATPX power control (\_SB.PC00.GFX0.ATPX) but never defines the PEG0.PEGP._OFF/_ON symbols its body calls, so the first idle resume of the headless R9700 leaves it in runtime_status = error (resume of IP block <smu> failed -62) until reboot, and amdgpu discards the ACPI error. Root cause, kernel-source trail and the measured field comparison: hosts/idols-aquamarine/ROCM.md.	Drop once a BIOS update defines those ACPI methods (upstream releases 1023/1066 exist for this board; a flash changes PCR7, so re-enroll TPM2), or a kernel release stops trusting ATPX when its power methods are missing	2026-10-14	on a BIOS update or kernel bump	active

If WA-008 freezes recur, the fallback is to restore the parameters commented out in hosts/idols-ai/hardware-configuration.nix — nvme_core.default_ps_max_latency_us=0 nvme_core.io_timeout=4294967295 pcie_aspm=off; this is a recovery procedure, not its removal condition.

If Wi-Fi wedges after a failed association, restart the stack instead of rebooting: sudo systemctl restart wpa_supplicant, then sudo systemctl restart NetworkManager. Deleting an active NetworkManager profile wedges the supplicant as well; switch to another profile first, and only delete inactive duplicates.

Known issues

A known limitation with no fix yet.

ID	What & where	Why	Removal condition	Added	Revisit	Status
WA-016	subscription rule snapshots — modules/nixos/desktop/networking/mihomo/ (rules_from:)	mihomo's proxy-providers imports proxies only, so the rules and proxy-groups a subscription ships with are dropped by the core; the generator re-imports them from a local YAML copy that has to be refreshed by hand when the provider changes its routing policy	Drop the snapshots once mihomo can import rules from a proxy-provider, or the providers publish their rules as rule-providers	2026-10-04	when mihomo gains rule import	active
WA-022	qemu-user binfmt removed — hosts/12kingdoms-shoukei/hardware-configuration.nix	the x86-on-arm module owns the x86 ELF handlers and this host does not need riscv64, but dropping boot.binfmt.emulatedSystems also drops nix.settings.extra-platforms and qemu-user, so podman run --platform=linux/amd64, x86 chroots and local builds of uncached x86 derivations need a remote x86_64 builder	Restore boot.binfmt.emulatedSystems (without x86_64/i686, which the module asserts against) if such a workload is needed	2026-10-07	when an amd64 container/chroot or uncached x86 build is needed	active
WA-025	brcmfmac 4-way-handshake offload authentication — upstream kernel/wpa_supplicant, no code in this repo	Since hostap commit 416386060, wpa_supplicant 2.11+ expects NL80211_CMD_PORT_AUTHORIZED from drivers that offload the 4-way handshake; brcmfmac never reports it, so authentication intermittently fails on Apple Silicon (BRCM4378/4387/4388). nixpkgs already carries the Broadcom revert in wpa_supplicant 2.12; the proper fix, Janne Grunau's wifi: brcmfmac: cfg80211: Report port_authorized for 4-way HS offload (2026-09), is still under review. Entering the key again after such a failure only creates a duplicate profile, so cancel and retry instead	Fix lands via a nixpkgs kernel update (or by carrying the patch through nixpkgs-patched)	2026-10-07	on every kernel bump	active
WA-033	USB-C/XHCI port _PLD ACPI noise — this board's DSDT, no code in this repo	every boot logs 16 ACPI Error: Aborting method \_SB.PC00.TXHC.RHUB.SS01._PLD ... (AE_NOT_FOUND) lines, plus \_SB.PC02.XHCI.RHUB.HS01._PLD; the ports work, and these messages are unrelated to the GPU's ATPX failure, which names \_SB.PC00.GFX0.ATPX instead	Drop if a BIOS update defines the _PLD descriptors	2026-10-14	on a BIOS update	active
WA-034	IPv6-first resolution is dead on the wired link — hosts/idols-aquamarine/default.nix (networking.getaddrinfo.precedence)	the proxy gateway answers DNS in fake-IP mode and its IPv6 path is dead: an AAAA lookup returns a fake address whose connection fails at once (measured: curl -6 fails in 8 ms, curl -4 answers in 0.7 s). glibc clients are covered by the RFC 6724 table with the IPv4-mapped row raised; nix's libcurl and other non-glibc resolvers ignore /etc/gai.conf. Disabling IPv6 with boot.kernel.sysctl did not work here — networkd re-enables it on the wired link for DHCP = "ipv6"/IPv6AcceptRA — so that setting was dropped on 2026-10-14	Drop once the gateway serves proxied names over IPv6 as well (the adjacent fix is dns.ipv6: false in mihomo, see WA-030)	2026-10-14	on a mihomo or gateway change	active
WA-035	SSH retry + multiplexing to LAN peers, ARP fallback tuning — home/base/tui/ssh.nix, hosts/idols-ai/neighbour-probe.nix	the desktop reaches the LAN over a Mesh WiFi backhaul, which drops unicast to a peer whose MAC it has aged out of its forwarding table while still flooding broadcast: a capture shows seven SYNs from one socket addressed to the cached MAC with no answer, three unicast ARP probes unanswered, then a broadcast ARP answered in 0.4 ms after ~12 s of failed connects. The ssh settings retry a short connect and keep a master warm so the entry stays fresh; the neighbour-probe tunings walk the kernel to that broadcast fallback in ~1 s	Drop once the backhaul is wired or the mesh stops dropping unknown unicast	2026-10-16	when the backhaul changes	active

WIP

An unfinished feature or gap.

ID	What & where	Why	Removal condition	Added	Revisit	Status
WA-013	NixOS tests — outputs/README.md	full-host tests still rebuild custom packages (no private cache) and need the host ssh key to decrypt agenix; the shared-firewall security-exporters VM test now runs in CI (KVM); outputs/x86_64-linux/nixos-tests/idols-ruby.nix is exposed as packages.x86_64-linux.ruby-nixos-tests but is not in checks or CI	Resolve when a private cache exists and tests can run per-service	2024-03-13	quarterly	active
WA-027	NFS golden store no_root_squash — hosts/12kingdoms-youko/nfs-golden.nix	the existing PVC subdirectories are root-owned, so enabling root_squash would break running workloads until they are migrated; the CSI node plugin is hostNetwork and sources from the allowlisted node IPs	Drop when the PVC subdirectories are migrated and root_squash is enabled	2026-10-07	next maintenance window	active

Related

• Security architecture, threat model and audit status: SECURITY.md.
• Unmerged nixpkgs PRs are carried via the nixpkgs-patched input and the .agents/skills/nixpkgs-patched workflow (that input currently carries nothing; package-level carries are recorded under Pins).
• Routine version pins (colmena, agenix, disko, lanzaboote, haumea, home-manager, nixpkgs-stable, nixpkgs-darwin, …) are the versions in use, not workarounds, so they are not listed here.