Nomarchy/docs/TROUBLESHOOTING.md

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 and Migration Guide 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:

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:

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 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:

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:

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:91-120 (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:

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 — every nomarchy.* setting.
• Existing-NixOS install: docs/MIGRATION.md — how to layer Nomarchy onto a working NixOS without reformatting.
• Repo layout: docs/STRUCTURE.md — where each module lives.
• Roadmap: docs/ROADMAP.md — what's planned and what's shipped.