name	fix-nix-build
description	Use when a nix build is failing — after `just update` / flake update, in CI, or on rebuild ("i did an update and its failing", "build is broken", "CI is red"). Triage the failing derivation, find the upstream issue, apply a commented workaround, verify with a build — never switch.

fix-nix-build

The recurring post-update breakage workflow.

Respect the Build Policy in AGENTS.md: small stuff builds locally on saturn, chunky/aarch64 goes through CI + cachix, NEVER build or eval on eros, --cores 1 if Alex is gaming.
Build only. Never nh os switch or activate anything — Alex switches herself. When the fix is ready, wl-copy the switch command.
"CI is failing" unqualified = the saturn toplevel.
Flakes only see git-tracked files — git add new files before building.

Reproduce cheaply. For eval errors, nix eval the failing attribute first — much faster than a build. Otherwise build the toplevel in the background and watch the log: nix build .#nixosConfigurations.saturn.config.system.build.toplevel --no-link
Isolate the failing derivation from the log — the actual package that failed, not the toplevel that depends on it.
Check upstream before hand-rolling anything. Search nixpkgs issues/PRs and the package's own repo for the error message. Post-update breakage is almost always already reported, often with a fix in flight.
Fix, in preference order:
- pin/roll back the offending flake input or use the fixed PR's commit
- overlay/override (patch, version pin, disabled test)
- config escape hatch (permittedInsecurePackages, feature toggle)
- disable the affected module and say so
Comment every workaround with the upstream issue link and the condition for removing it — a note to future sessions.
Verify with a rebuild, then report: what broke, root cause, the fix, and when it can be unwound. wl-copy nh os switch if it's ready to apply.

name	fix-nix-build
description	Use when a nix build is failing — after `just update` / flake update, in CI, or on rebuild ("i did an update and its failing", "build is broken", "CI is red"). Triage the failing derivation, find the upstream issue, apply a commented workaround, verify with a build — never switch.

The recurring post-update breakage workflow.

Respect the Build Policy in AGENTS.md: small stuff builds locally on saturn, chunky/aarch64 goes through CI + cachix, NEVER build or eval on eros, --cores 1 if Alex is gaming.
Build only. Never nh os switch or activate anything — Alex switches herself. When the fix is ready, wl-copy the switch command.
"CI is failing" unqualified = the saturn toplevel.
Flakes only see git-tracked files — git add new files before building.

Reproduce cheaply. For eval errors, nix eval the failing attribute first — much faster than a build. Otherwise build the toplevel in the background and watch the log: nix build .#nixosConfigurations.saturn.config.system.build.toplevel --no-link
Isolate the failing derivation from the log — the actual package that failed, not the toplevel that depends on it.
Check upstream before hand-rolling anything. Search nixpkgs issues/PRs and the package's own repo for the error message. Post-update breakage is almost always already reported, often with a fix in flight.
Fix, in preference order:
- pin/roll back the offending flake input or use the fixed PR's commit
- overlay/override (patch, version pin, disabled test)
- config escape hatch (permittedInsecurePackages, feature toggle)
- disable the affected module and say so
Comment every workaround with the upstream issue link and the condition for removing it — a note to future sessions.
Verify with a rebuild, then report: what broke, root cause, the fix, and when it can be unwound. wl-copy nh os switch if it's ready to apply.

المزيد من هذا المستودع