I ran into a confusing error today while trying to update my Neovim colorscheme in chezmoi.

chezmoi add ~/.config/nvim/lua/plugins/colorscheme.lua

The error made no sense:

chezmoi: stat /home/vscode/.local/share/chezmoi/dot_config/plugins: no such file or directory

It was looking for dot_config/plugins instead of dot_config/nvim/lua/plugins. The path was completely wrong.

The Problem

After some digging, I found the culprit in .chezmoiexternals:

[".config/nvim"]
type = "archive"
url = "https://github.com/LazyVim/starter/archive/refs/heads/main.tar.gz"
stripComponents = 1

My nvim config is managed as an external archive. Chezmoi pulls the LazyVim starter as a base, then merges my local files from dot_config/nvim/ on top.

When you have an external managing a directory, chezmoi add gets confused. It doesn’t understand the merge hierarchy and tries to create a broken path.

The Fix

For files that overlay an external archive, you have to manually copy them to the source directory:

cp ~/.config/nvim/lua/plugins/colorscheme.lua \
   ~/.local/share/chezmoi/dot_config/nvim/lua/plugins/colorscheme.lua

Then verify with:

chezmoi diff ~/.config/nvim/lua/plugins/colorscheme.lua

No output means you’re synced.

When This Happens

This gotcha applies whenever you:

  • Use .chezmoiexternal to pull a git repo or archive as a base
  • Want to modify files within that external’s directory
  • Try to use chezmoi add to track those modifications

The external provides the foundation, your source state provides the overrides, but chezmoi add can’t reconcile the two.

The Takeaway

If you’re using chezmoi externals for things like Neovim configs, shell frameworks, or other “starter” setups - remember that chezmoi add won’t work for files inside those directories. Manual copying to the source state is the way.

If you want to learn my complete dev container worfklow and get access to all my dotfiles, visit https://kubecraft.dev