Skip to content
Skills Library
DevOps & cloud · Analysis

nix-debug

/nix-debug

Find why a Nix evaluation, build, activation, service or boot fails. Update inputs, pins, hashes and carried patches safely. Use for a failed nix flake check, build or deploy, a flake.lock bump, or a rescue from a live USB.

Repository
skills ↗
Licence
MPL-2.0
Last repository change
12.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.

Licence

MPL-2.0, otwarta.

What it does and when to use it

Find why a Nix evaluation, build, activation, service or boot fails. Update inputs, pins, hashes and carried patches safely. Use for a failed nix flake check, build or deploy, a flake.lock bump, or a rescue from a live USB.

Original author description

Find why a Nix evaluation, build, activation, service or boot fails. Update inputs, pins, hashes and carried patches safely. Use for a failed nix flake check, build or deploy, a flake.lock bump, or a rescue from a live USB.

How it works

  1. 1. Find the layer
  2. 2. Evaluation and build
  3. 3. Updates are supply-chain events
  4. 4. Rescue from a live USB
  5. Rules
Original SKILL.md headings · 61 lines, 451 words
SKILL.md preview
---
name: nix-debug
description: "Find why a Nix evaluation, build, activation, service or boot fails. Update inputs, pins, hashes and carried patches safely. Use for a failed nix flake check, build or deploy, a flake.lock bump, or a rescue from a live USB."
---

# nix-debug

First find the layer where the failure occurs. Then fix it in that layer only.

## 1. Find the layer

| Layer | Symptom | First command |
|---|---|---|
| Evaluation | `error:` with a Nix trace, before any build | `nix flake check --no-build --show-trace` |
| Build | a derivation fails, `builder for ... failed` | `nix log <drv>` |
| Activation | the switch fails, or a unit fails right after it | `journalctl -b -u <unit>` |
| Runtime | the system runs, a service misbehaves | `systemctl status <unit>`, then the journal |
| Boot | the machine does not start | section 4 |

## 2. Evaluation and build

- Read the trace from the bottom. The last frame in your own files is usually the cause.
- Read one value: `nix eval .#<path>`. Inspect a set: `nix repl` then `:lf .`.
- An option name that you are not sure of: search the option. Do not guess.
- A hash mismatch: set `lib.fakeHash`, build, then copy the `got:` hash. Never copy a hash from
  a web page.
- A build that works on one machine only: check the `system`, the sandbox and an impure path.

## 3. Updates are supply-chain events

1. Update one input at a time: `nix flake update <input>`.
2. Read what moved: `git diff flake.lock`, and the upstream log between the two revisions.
3. Build before and after. Compare the closures: `nix run nixpkgs#dix -- <old> <new>`.
4. Run the full gate.
5. Open a PR with only the update, its closure difference and the inputs that moved.

For a package pin: change the version, set the hash to `lib.fakeHash`, build, copy the real
hash. For a carried patch: rebase it on the new source. If upstream merged it, delete it. Say
which in the PR.

Before you rely on an open nixpkgs PR, build its attribute and read its diff. Do not trust it
because it has approvals.

## 4. Rescue from a live USB

Use this only with the owner present. Each step changes a real disk.

```bash
lsblk -f                                        # find root, boot and any LUKS volume
sudo cryptsetup open /dev/<dev> root            # only for LUKS
sudo mount /dev/disk/by-label/nixos /mnt
sudo mount /dev/disk/by-label/boot /mnt/boot    # UEFI only
sudo nixos-enter --root /mnt                    # a shell in the installed system
```

Inside: list the generations (`nix-env -p /nix/var/nix/profiles/system --list-generations`).
Switch to the last good one, or rebuild from the flake. Reinstall the bootloader only when the
bootloader is the cause.

## Rules

- Read the error before you change code.
- Change one thing, then build again.
- Never make a check weaker to get a pass.

Versions

The database has no other skills named nix-debug.

Database snapshot: 13.11.2026 · package version ef48f7ae43c0 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100nix-flake-init
    Use when a project needs a new Nix flake, or its flake lacks pinned inputs, a real build, a dev shell, or checks.
  • 96nix-best-practices
    Use when working with Nix flakes, overlays, shell.nix, or flake.nix files.
  • 100nix-for-dev
    Use this when setting up Nix for a development project (devShell + package build) and you care about `nix develop` being fast. Covers the zero-inputs flake.nix + npins + default.nix/shell.nix layout, sub-flakes for non-user-facing Nix, and language-specific recommendations.
  • 96nix
    Write and review Nix code. Use when a task touches a `.nix` file.
  • 100nix-scaffolding
    Use when creating a new project from scratch that needs Nix flake setup with devshell
  • 100nix-config-debug
    Use when something here is broken or stops working: an eval or build error, a failed activation, a dead or restarting unit, a mihomo or DNS outage, an unreachable host or MicroVM guest, or a failing CI action.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.