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-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-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-020	fcitx5-vinput pinned to release tag v2.4.2 — 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
WA-037	nixpkgs-npu input pinned to 2ddccb854d89 — the openvino-npu-compiler branch of ryan4yin/nixpkgs, carrying NixOS/nixpkgs#570230 — flake.nix; consumer pkgs-npu in outputs/default.nix, hosts/idols-aquamarine/asr.nix	The Intel NPU compiler, and the driver change that loads it, are unmerged, so the NPU driver the Whisper service needs comes from that branch	Drop the input and load intel-npu-driver from nixos-unstable once #570230 merges	2026-10-17	when #570230 merges	active

Workarounds

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

ID	What & where	Why	Removal condition	Added	Revisit	Status
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
WA-036	catppuccin eval-time ports kept in the home closure (home.extraDependencies) — home/base/core/theme.nix	catppuccin/nix reads some ports at eval time (lib.importTOML "${sources.starship}/<flavor>.toml") and inlines the result, so the built port, catppuccin's build/install hooks and the fetched port source stay unreachable: every gc deletes them, and the deploy after it rebuilds them (build logs: 2026-10-16). home.extraDependencies records the port in the generation, which is a gc root. Also read at eval time upstream: bottom, element (option element-desktop), firefox, rio, palette (options skim, tty), spotify-player.	Drop once catppuccin/nix stops reading port files at eval time, or those ports come from a binary cache	2026-10-16	on a catppuccin bump	active
WA-039	niri's NVIDIA free-buffer pool bounded (GLVidHeapReuseRatio 0) — hosts/idols-ai/hardware-nvidia.nix	the driver does not return freed vidmem buffers to its free pool, so niri's VRAM grows to ~1.1 GiB instead of the ~100 MiB its NVIDIA notes expect (measured 1137 MiB after 24 h uptime; NVIDIA/egl-wayland#126)	Drop once a driver stops growing niri's VRAM without the profile, or niri ships its own default	2026-10-19	on an nvidia driver bump	active
WA-041	Monitor OSD "no-signal auto power-off" disabled — no code in this repo (the P32A2V OSD setting)	during a DPMS-off idle the panel drops and re-adds HPD every ~13 s, and after wake niri keeps scanning out while the panel stays dark until the monitor is power cycled; the panel's own auto power-off drives that state, so it is now disabled. Pinning the mode to 120 Hz did not change the symptom	Drop once a driver retrains the DP link after a DPMS wake, the monitor firmware stops cycling HPD, or this monitor is replaced	2026-10-21	confirm on the next full idle cycle, then on an nvidia or monitor firmware update	active
WA-042	Colmena nodes set system.nixos.versionSuffix and revision from the flake's lib — outputs/default.nix (rawColmenaHive)	Colmena evaluates each node with nixpkgs' eval-config.nix and plain lib, which reports 26.11pre-git, so without the override a Colmena deploy differs from the nixosConfigurations toplevel; the colmena-parity eval test guards the match	Drop once Colmena evaluates nodes with the flake's lib or accepts nixosConfigurations directly, keeping colmena-parity green	2026-10-21	on a colmena bump	active
WA-046	xdg-desktop-portal-wlr pinned to 0.8.2 — modules/nixos/desktop/xdg.nix	niri's GNOME ScreenCast path exposes only DMA-BUF with modifiers, which Zoom 7.2.1 rejects; xdg-desktop-portal-wlr 0.8.2 provides the working SHM path, while 0.8.4 regresses Zoom's SelectSources.	Drop once niri's ScreenCast path works with Zoom or xdg-desktop-portal-wlr 0.8.4+ is fixed.	2026-10-31	on xdg-desktop-portal-wlr or Zoom updates	active

| WA-048 | Nixpak GUI fontconfig comes from the host — hardening/nixpaks/modules/desktop-base.nix | Nixpak normally generates a standalone /etc/fonts and font package list for each sandbox; that bypasses the host defaultFonts and made browser chrome, Telegram, QQ and other sandboxed apps choose a different CJK fallback from the host. The wrapper now disables Nixpak fonts and bind-mounts /etc/static/fonts at /etc/fonts, so sandboxed GUI apps reuse the host font packages and family preferences through the already-mounted /nix/store. | Drop once Nixpak can directly reuse the host fontconfig or no longer overrides /etc/fonts, then remove the bind and restore the library-supported configuration path | 2026-11-01 | on a nixpak update | active |

If the KINGBANK KP260 NVMe freezes on ai recur (formerly WA-008, now back at the kernel's APST defaults), 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.

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-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
WA-038	OpenVINO GPU plugin needs an ocl-icd loader — hosts/idols-aquamarine/hardware-intel-igpu.nix (openvino-gpu wrapper)	/run/opengl-driver/lib/libOpenCL.so.1 comes from ROCm's clr, which provides OpenCL 2.2 symbols, while OpenVINO's GPU plugin links the OpenCL 3.0 loader (ocl-icd): the plugin fails to load and OpenVINO silently omits GPU from available_devices. The wrapper runs a command with ocl-icd first on LD_LIBRARY_PATH and OCL_ICD_VENDORS pinned to the Intel ICD	Drop once nixpkgs' openvino GPU plugin carries an explicit ocl-icd RUNPATH, or ROCm's clr ships an OpenCL 3.0 loader	2026-10-18	on an openvino or ROCm 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); 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
WA-044	transmission AppArmor lock permission — hosts/12kingdoms-youko/homelab-services/transmission.nix	nixpkgs' transmission 4.1.4 profile grants rw on the daemon's config dir but not k, while 4.1.4 takes an fcntl lock on ~/.config/transmission-daemon/lock; the daemon exits with "Another process is already using". A local/bin.transmission-daemon include adds rwk for that lock file only	Drop once the nixpkgs profile includes the lock permission	2026-10-31	on the next nixpkgs bump	active
WA-045	Chromium cookie crypto — hardening/nixpaks/modules/chromium-browser.nix	Chromium-family browsers use the app-scoped Secret portal and write v12 cookies. If the portal is unavailable, Chromium may fall back to weak v10 storage.	Drop once the v10 fallback is eliminated; monitor portal initialization and the Local State.os_crypt.portal.prev_init_success flag	2026-10-31	on Chromium updates	active gap

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 (currently none).
• 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.