.dotfiles Manual

Cookbook

Cookbook: Troubleshooting

Symptom → cause → fix.

Installation

Symptom: install.sh fails with "chezmoi not found"

Cause: /usr/local/bin or ~/.local/bin not in PATH at install time.

Fix:

export PATH="$HOME/.local/bin:$PATH"
# Re-run only the installer that was release-pinned and SHA256-verified.
bash /tmp/dotfiles-install.sh

Symptom: "could not create directory ~/.local/share/chezmoi"

Cause: Permission issue on ~/.local.

Fix:

mkdir -p ~/.local/share ~/.local/state ~/.local/bin
chmod 755 ~/.local ~/.local/share

Symptom: Install hangs at "Downloading chezmoi"

Cause: Slow network or corporate proxy.

Fix:

export https_proxy=$HTTP_PROXY  # if applicable
# Or pre-download chezmoi manually
brew install chezmoi            # macOS
apt install chezmoi             # Debian 13+

Apply / Sync

Symptom: dot apply reports "file modified, skipping"

Cause: Chezmoi detected local drift on a managed file.

Fix:

dot diff                    # see what differs
dot apply --force           # overwrite local
# OR
dot add <path>              # import local change to source

Symptom: "template: error calling index"

Cause: A template references a missing data field.

Fix: Check that your .chezmoidata.toml has the required field. For example:

chezmoi execute-template '{{- $hw := index .hardware .machine -}}{{ $hw.wm }}'

If machine is not set in your ~/.config/chezmoi/chezmoi.toml, index returns nil. Set:

[data]
machine = "macbook-t2"

Symptom: Apply succeeds but shell doesn't reflect changes

Cause: Cached init scripts are stale.

Fix:

dot clean-cache
dot prewarm
exec $SHELL -l

Theme

Symptom: dot theme shows no themes

Cause: No wallpapers discovered, themes.toml not generated.

Fix:

dot theme rebuild --force

Symptom: dot theme <name> errors "unknown theme"

Cause: Theme name doesn't exist in themes.toml.

Fix:

dot theme list            # see valid names
dot theme rebuild --force # regenerate if expected but missing

Symptom: macOS accent color doesn't update

Cause: System Settings UI cached the old value.

Fix: dot-theme-sync now calls killall cfprefsd SystemUIServer Dock "System Settings". If it still doesn't refresh:

killall -KILL Dock SystemUIServer
sudo killall -KILL cfprefsd

Or log out and back in.

Symptom: Wallpaper not applying

Cause: Wrong format or missing DE support on Linux.

Fix:

# Check the wallpaper file exists
ls -la ~/Pictures/Wallpapers/

# On Linux, verify HEIC → PNG conversion tool
command -v magick || command -v heif-convert || command -v convert
# Install if needed:
sudo apt install imagemagick-7

Symptom: Theme applies but Ghostty doesn't reload

Cause: Ghostty DBus or SIGUSR2 signaling failed.

Fix:

# Restart Ghostty manually, or:
pkill -USR2 ghostty 2>/dev/null
# Or quit+relaunch the app

Secrets

Symptom: "could not decrypt: no age key"

Cause: ~/.config/age/keys.txt missing or unreadable.

Fix:

ls -la ~/.config/age/keys.txt
# Should be: -rw------- 1 user user
chmod 600 ~/.config/age/keys.txt

# If missing, restore from password manager or regenerate (requires re-encrypting all secrets)

Symptom: SOPS says "wrong recipient"

Cause: Your Age public key isn't listed in the file's recipients.

Fix:

# Add your public key to .sops.yaml
sops updatekeys path/to/file.sops.yaml

# Or, ask a recipient to re-encrypt for you

Symptom: Plaintext leak detected by gitleaks

Cause: A secret was committed to Git history.

Fix:

# Immediate mitigation
dot verify --security   # confirm which file
git rm --cached <file>
echo "<file>" >> .gitignore
git commit -sS -m "fix(security): remove leaked file"

# Rotate the leaked secret upstream (it's now public)
# Rewrite Git history if needed (requires force-push):
git filter-repo --path <file> --invert-paths

Performance

Symptom: Shell startup >500ms

Cause: Heavy modules loaded synchronously.

Fix:

dot benchmark --detailed
# Identify which module is slow

# Rebuild caches
dot prewarm

# Disable heavy modules temporarily
# Edit ~/.config/zsh/.zshrc.local (or equivalent) to skip them

Symptom: dot doctor score <70

Cause: Multiple health issues.

Fix:

dot doctor --verbose    # see every failure
dot heal                # auto-fix what's possible
dot doctor              # recheck

Symptom: Mise tools not found

Cause: Mise shim not activated.

Fix:

eval "$(mise activate zsh)"  # or fish, bash
dot doctor                    # confirm

Build Artifacts

Symptom: Cargo builds to target/ instead of /tmp/builds/cargo

Cause: ~/.cargo/config.toml not managed or was overridden.

Fix:

chezmoi apply ~/.cargo/config.toml
cat ~/.cargo/config.toml | grep target-dir
# Should be: target-dir = "/tmp/builds/cargo"

Symptom: /tmp/builds/ doesn't exist

Cause: Created by shell init, but shell wasn't restarted.

Fix:

mkdir -p /tmp/builds
# Or restart shell
exec $SHELL -l

Fleet

Symptom: dot fleet attest hangs

Cause: A fleet host is unreachable.

Fix:

# Check connectivity to each host
for host in macbook-t2 surface-pro geekom-a9; do
  ssh -o ConnectTimeout=5 $host 'echo OK' || echo "FAIL: $host"
done

# Remove unreachable hosts from ~/.config/dotfiles/fleet.toml temporarily

Symptom: Attestation signature fails

Cause: Remote host's SSH public key not in local ~/.ssh/allowed_signers.

Fix:

# On the remote host:
ssh remote-host 'cat ~/.ssh/id_ed25519.pub'
# Copy the output and append to your ~/.ssh/allowed_signers

CI

Symptom: PR fails on "Shell Lint (Zero Warnings)"

Cause: shfmt formatting differs from canonical.

Fix:

shfmt -w -i 2 -ci scripts/**/*.sh install.sh .chezmoitemplates/**/*.sh
# Commit the changes

Symptom: PR fails on "100% Coverage"

Cause: New code added without tests.

Fix:

bash examples/example-coverage-gate.sh
# Identifies uncovered modules

# Add a test in tests/unit/<domain>/test_<module>.sh

Symptom: Checkov SARIF upload times out

Cause: Known infrastructure flake (Azure runner slow apt mirrors).

Fix: The workflow already guards this with hashFiles('reports/checkov.sarif'). If you see this after the guard was added, check the Checkov step output for errors.

Getting More Help

  1. Check FAQ
  2. Read the relevant concept chapter
  3. Open an issue: https://github.com/sebastienrousseau/dotfiles/issues

When filing an issue, include:

dot doctor --json
dot version
uname -a
chezmoi --version

See Also