nix-config/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	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>, not just microvm-deploy — 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	2026-10-09	on microvm.nix or nix bump	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

If WA-008 freezes recur, the fallback is to restore 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

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)	Resolve when a private cache exists and tests can run per-service	2024-03-13	quarterly	active
WA-020	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.