Troubleshooting

Deployment Issues

clan machines deploy fails with SSH errors

Error: Connection refused / Permission denied

• Verify the machine is reachable: ping <machine>.local
• Check SSH key is in lib/ssh-keys.nix and deployed via sshd instance
• Verify deploy.targetHost in flake.nix is correct
• For Darwin: ensure luxus@<machine>.local (not root)
• For NixOS: ensure root@<machine>.local

nix-daemon: not found when deploying Darwin from another host

remote-program=bash -lc 'exec nix-daemon --stdio'
--stdio: line 1: exec: nix-daemon: not found
Failed to upload sources

Clan uploads flake sources to the Darwin target before building. That SSH session runs nix-daemon by name, but standalone Nix installs keep it under /nix/var/nix/profiles/default/bin, which is often missing from non-interactive login shells.

Permanent fix: modules/darwin/nix-clan-deploy.nix adds that path via environment.systemPath. Apply it once on the Mac (chicken-and-egg: remote deploy cannot work until this is active):

## on zoe/emily, from a checkout of this flake
darwin-rebuild switch --flake .#zoe

One-time unblock (if you cannot rebuild yet): replace stale shell symlinks (e.g. from prior HM use) and put the daemon on PATH for bash -lc:

rm -f ~/.bash_profile ~/.profile ~/.bashrc
printf '%s\n' 'export PATH="/nix/var/nix/profiles/default/bin:$PATH"' > ~/.bash_profile

Then retry clan machines update zoe from lea.

Nix evaluation errors

Error: attribute 'X' missing

• Run nix flake check --no-build to identify the issue
• Check that all referenced modules exist (run scripts/validate-inventory.sh)
• Verify flake inputs are up to date: nix flake update

Secret generation prompts loop forever

clan vars generate --machine <machine>

• Check that the secret’s promptType is correct in lib/secret-registry.nix
• For hidden type: input is masked; press Enter after typing
• For line type: input is visible
• If a secret was already set, it won’t re-prompt unless the var is deleted first

MicroVM won’t start

• Check host prerequisites: systemctl status microvm@<vm>
• Verify prep service ran: systemctl status agent-vm-prep-<vm>
• Check secret bundle: ls /var/lib/microvm-bundles/<hostname>/secrets/
• Check project mount exists: ls /srv/agent-projects/<name>/
• Run scripts/verify-agent-vms.sh from emily; see Agent VM Architecture

Hjem Issues

Profile import conflicts

error: The option 'rum.programs.X' in '/path/to/A.nix' is already declared in '/path/to/B.nix'

• Don’t import overlapping app modules twice (e.g. git in both minimal-darwin.nix and a separate git.nix)
• Choose one base profile per machine, then layer extras on top
• Profile hierarchy: minimal-darwin → base → development → platform-specific

Package build failures on Darwin

• Some packages don’t support aarch64-darwin — check lib.optionals (!pkgs.stdenv.isDarwin)
• Streamlink has doCheck = false overlay in emily’s config for this reason
• Use nixpkgs-review to test package builds locally

Clan Vars / Secrets

Secret not available at deploy time

• Ensure the secret is in lib/machine-env-matrix.nix for that machine
• Run clan vars generate --machine <machine> to populate
• Check that lib/vars-generators.nix is imported in the machine config

How to reset a secret

## List all vars for a machine
clan vars list <machine>

## Delete and regenerate a specific secret
clan vars delete <machine> <generator-name>
clan vars generate --machine <machine>

Build Performance

Evaluation is slow

• Documentation is disabled in modules/nixos/common.nix (documentation.enable = false)
• Use binary caches listed in flake.nix nixConfig
• Run cachix use luxus to enable the project cache

Large closure size

• Use nix path-info -rsSh .#nixosConfigurations.<machine>.config.system.build.toplevel to inspect
• Consider using minimal-*.nix profiles for machines that don’t need dev tools
• The packages-llm.nix and packages-core.nix add significant packages

Common Commands

Task	Command
Check flake	nix flake check --no-build
Deploy	just update-<machine> or clan machines update <machine> (see justfile)
Generate secrets	clan vars generate --machine <machine>
List secrets	clan vars list <machine>
Format code	nix fmt
Validate inventory	scripts/validate-inventory.sh
Compare machines	scripts/diff-machines.sh <m1> <m2>
Evaluate config	nix eval .#nixosConfigurations.<machine>.config.system.build.toplevel.drvPath --no-write-lock-file

Resolved Cleanups (2026)

• SDDM greeter idle blanking on primary (#85) is obsolete: lea now uses greetd + noctalia-greeter by default (see services/desktop/default.nix, modules/hosts/lea/default.nix).
• kmonad removed entirely from lea (#110): EurKEY XKB layout is used instead. No kmonad references remain in the tree.
• Per-app QT_QUICK_CONTROLS_STYLE=Basic workarounds eliminated (#111): EasyEffects and similar now use the consolidated global QML/Union environment from lib/kde-settings-qml.nix + hjem/profiles/kwin-noctalia.nix.
• Hjem migration children (#87–#94, #96) closed: full fleet migrated off Home Manager (see modules/clan/hjem-users.nix, hjem/, flake.nix has no home-manager input).

See inventory.md, configuration-matrix.md and services/README.md for current state.