Files
nix-config/WORKAROUNDS.md
T
Ryan Yin e975f69383 docs: add a workaround registry with removal conditions
WORKAROUNDS.md collects temporary workarounds, version pins, carried patches, and known gaps, each with a removal condition, so they can be re-evaluated and rolled back on a schedule. AGENTS.md points to it and states the convention: a change that adds a workaround adds a row in the same PR.
2026-10-03 12:53:30 +08:00

11 KiB

Workarounds & known gaps

Temporary workarounds, version pins, carried patches, and known gaps are collected here, 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 here 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.

Types

Type Meaning
patch Upstream code carried locally (an overlay, a patch file, or a fork branch).
pin A version or revision pinned for a reason that can go away.
workaround A setting that works around a bug or a hardware quirk.
known-issue A known limitation with no fix yet.
wip An unfinished feature or gap.

Registry

ID Type What & where Why Removal condition Added Revisit Status
WA-001 pin 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 smartctl_exporter 0.15.0 is released and packaged in nixpkgs 2026-10-03 next nixpkgs bump active
WA-002 pin 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 pin 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 pin 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 pin 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 pin 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 pin 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-008 workaround 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 Keep relaxed while kernel logs stay clean; restore nvme_core.default_ps_max_latency_us=0 nvme_core.io_timeout=4294967295 pcie_aspm=off if freezes return 2026-10-03 watch NVMe timeout/reset/AER in the journal active
WA-009 workaround 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 workaround 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 workaround Kernel module blacklist (esp4, esp6, rxrpc) — modules/nixos/base/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-012 known-issue Apple Silicon 16k page size — hosts/12kingdoms-shoukei/apple-silicon.nix some x86_64 apps and games need muvm, which is currently disabled Hardware limitation; revisit when Asahi or muvm support changes — on Asahi changes active
WA-013 wip NixOS tests — outputs/README.md tests rebuild custom packages (no private cache) and hosts need their own ssh host key to decrypt agenix Resolve when a private cache exists and tests can run per-service 2024-03-13 quarterly active
  • Unmerged nixpkgs PRs are carried via the nixpkgs-patched input and the .agents/skills/nixpkgs-patched workflow (that input currently carries nothing; the patch rows above are per-package overlays instead).
  • 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.