4b2f16c2f0
Covers: option-already-declared (duplicate mkOption), attribute-missing (forgot to import nomarchy.nixosModules.system), Stylix target conflict (needs lib.mkForce, not bare bool), home-manager .hm-bak churn (left over from backupFileExtension after first install), and impermanence path missing (dir not in environment.persistence list). Each entry has the literal error text, the cause, and a copy-paste fix. Linked from README.md and docs/MIGRATION.md so users hit it before guessing.
122 lines
5.1 KiB
Markdown
122 lines
5.1 KiB
Markdown
# Troubleshooting
|
|
|
|
The five rebuild errors a Nomarchy user is most likely to hit, with copy-paste fixes. If your error isn't here, the [Options Reference](OPTIONS.md) and [Migration Guide](MIGRATION.md) cover most other surfaces.
|
|
|
|
---
|
|
|
|
## 1. `error: The option 'X' is already declared in multiple modules`
|
|
|
|
**Looks like:**
|
|
|
|
```
|
|
error: The option `services.foo.enable' is already declared in multiple modules:
|
|
- /nix/store/…-source/modules/foo.nix
|
|
- /nix/store/…-source/core/system/foo.nix
|
|
```
|
|
|
|
**Cause:** Two modules — usually one of yours and one of Nomarchy's — both `mkOption` the same path. Nix can't merge two declarations of the *same option*; it can only merge two *values* for one option.
|
|
|
|
**Fix:** Find the duplicate. If it's yours and Nomarchy's, delete yours; Nomarchy already declares it. If it's two of yours, delete one. To grep:
|
|
|
|
```bash
|
|
grep -rn "options\..*foo\.enable" /etc/nixos
|
|
```
|
|
|
|
---
|
|
|
|
## 2. `error: attribute 'X' missing`
|
|
|
|
**Looks like:**
|
|
|
|
```
|
|
error: attribute 'nomarchy' missing
|
|
at /etc/nixos/system.nix:7:5:
|
|
7| nomarchy.system.formFactor = "laptop";
|
|
```
|
|
|
|
**Cause:** You're setting `nomarchy.*` options but didn't import the Nomarchy modules. The flake's `nixosModules.system` declares the option namespace; without the import, the option doesn't exist.
|
|
|
|
**Fix:** In your `/etc/nixos/flake.nix`, make sure both modules are in the system's `modules = [ … ]` list:
|
|
|
|
```nix
|
|
modules = [
|
|
nomarchy.nixosModules.system
|
|
./system.nix
|
|
./hardware-selection.nix
|
|
];
|
|
```
|
|
|
|
The home side is the same shape — `nomarchy.nixosModules.home` plus your `./home.nix`. See [MIGRATION.md](MIGRATION.md) for the full skeleton.
|
|
|
|
---
|
|
|
|
## 3. Stylix target conflict
|
|
|
|
**Looks like:**
|
|
|
|
```
|
|
error: The option `stylix.targets.gtk.enable' has conflicting definition values:
|
|
- In `/nix/store/…/stylix.nix': true
|
|
- In `/etc/nixos/home.nix': false
|
|
Use `lib.mkForce' or `lib.mkDefault' to resolve.
|
|
```
|
|
|
|
**Cause:** Stylix's per-target options are `bool`, not `enum`, so two equally-priority `true`/`false` values from two modules collide. Nomarchy's theming engine sets most targets to `true` via `mkDefault`, so the conflict almost always means *you* set one without `mkDefault`.
|
|
|
|
**Fix:** Wrap your override in `lib.mkForce`:
|
|
|
|
```nix
|
|
stylix.targets.gtk.enable = lib.mkForce false;
|
|
```
|
|
|
|
If you want the default-on behavior back, just delete your line — Nomarchy's default fires automatically.
|
|
|
|
---
|
|
|
|
## 4. home-manager `backupFileExtension` churn
|
|
|
|
**Looks like:** every rebuild leaves another `~/.config/foo/bar.conf.hm-bak` next to the file home-manager just wrote, until your `~/.config` is half backups.
|
|
|
|
**Cause:** home-manager refuses to overwrite files it didn't itself write; it backs them up first. Nomarchy's flake sets `backupFileExtension = "hm-bak"` (see `flake.nix:161,210`) so the first rebuild after a fresh ISO install doesn't fail — but every subsequent rebuild then re-backs-up the same files because the previous backup is still there.
|
|
|
|
**Fix:** After the first successful rebuild, delete the backups:
|
|
|
|
```bash
|
|
find ~/.config -name '*.hm-bak' -print -delete
|
|
```
|
|
|
|
If churn continues, you have a config under `~/.config/<app>/` that home-manager wants to manage but you've also touched by hand. Either let home-manager own it (don't edit by hand; use `nomarchy.*` options or `~/.config/nomarchy/overrides/`) or delete the home-manager declaration if you want the file to remain user-mutable.
|
|
|
|
---
|
|
|
|
## 5. impermanence path missing after a wipe
|
|
|
|
**Looks like:** after enabling `nomarchy.system.impermanence.enable = true;` and rebooting, an app forgets state — Bluetooth pairings vanish, NetworkManager forgets Wi-Fi, GPG keys are gone — or the rebuild itself errors with:
|
|
|
|
```
|
|
error: The path '/persist' does not exist
|
|
```
|
|
|
|
**Cause:** Impermanence requires (a) a `/persist` mountpoint that survives the boot wipe, and (b) every directory you want to keep must be in the persistence list. Nomarchy persists the basics in `core/system/impermanence.nix:46-72` (NetworkManager, Bluetooth, fprint, SSH host keys, the user's `.ssh` / `.gnupg` / Documents / Downloads / Pictures / Videos / Projects). Anything else you care about — Steam library, Flatpak data, custom dotfiles — must be added.
|
|
|
|
**Fix:** Make sure `/persist` is mounted (check `mount | grep persist`). Then add the missing path in your `system.nix`:
|
|
|
|
```nix
|
|
environment.persistence."/persist".users.nomarchy.directories = [
|
|
".local/share/Steam"
|
|
".var/app" # flatpak data
|
|
".local/share/keyrings" # already in Nomarchy defaults — example only
|
|
];
|
|
```
|
|
|
|
Per-app data lives in `~/.local/share/<app>` or `~/.var/app/<id>` (flatpak); check the app's docs. After adding, rebuild and reboot — the path is created on the next mount of `/persist`.
|
|
|
|
---
|
|
|
|
## Where to look next
|
|
|
|
- **Option reference:** [docs/OPTIONS.md](OPTIONS.md) — every `nomarchy.*` setting.
|
|
- **Existing-NixOS install:** [docs/MIGRATION.md](MIGRATION.md) — how to layer Nomarchy onto a working NixOS without reformatting.
|
|
- **Repo layout:** [docs/STRUCTURE.md](STRUCTURE.md) — where each module lives.
|
|
- **Roadmap:** [docs/ROADMAP.md](ROADMAP.md) — what's planned and what's shipped.
|