Skip to main content

Debugging Chezmoi Hooks

When chezmoi apply fails, the most useful piece of information is the exact hook script that failed.

Preconditions​

  • You can reproduce the failure locally.
  • You are running commands from the dotfiles source repo.

Steps​

  1. Re-run apply and capture the failing script path:
chezmoi apply
  1. Review diff/input templates:
chezmoi diff
  1. If the failing script is a template, render it:
chezmoi execute-template < home/.chezmoiscripts/<script>.tmpl
  1. Run the failing script directly to isolate environment/dependency issues.

Identify The Script​

The failing script path appears in chezmoi apply output.

Common Causes​

  • missing dependency (brew/mise/gh/op/uv)
  • auth required (GitHub CLI, 1Password CLI)
  • a script expects sudo access

Verification​

  • The failing command reproduces outside chezmoi apply.
  • After fixing root cause, chezmoi apply exits successfully.

Note: many hooks depend on binaries that are installed by earlier hooks (Homebrew, mise, etc.). If a hook fails with "command not found", check whether the earlier install hooks completed.

Rollback / Undo​

  • Revert the recent script/template changes in your working tree.
  • Re-run:
chezmoi apply