Troubleshooting¶

chezmoi doctor¶

Run chezmoi doctor after installation to check your setup. Most info lines are optional tools you don't need. Focus on warning and error lines.

source-dir / working-tree dirty¶

warning source-dir ~/.local/share/chezmoi is a git working tree (dirty)

You have uncommitted changes in your dotfiles repo. Normal during development — safe to ignore.

Fonts and Glyphs¶

Prompt icons or fastfetch render as boxes¶

The shell prompt (starship/oh-my-posh) and fastfetch require a Nerd Font. Without one, icons render as empty boxes or question marks.

The dotfiles install JetBrainsMono Nerd Font via chezmoi externals and update the font cache automatically. If glyphs are broken, ensure your terminal emulator is configured to use a Nerd Font.

Neovim¶

nvim-treesitter: gcc not found¶

Treesitter parsers need a C compiler to build. Available out of the box on macOS (Xcode CLI Tools) and Bluefin, but bare Debian/Fedora systems may need it:

# Debian/Ubuntu
sudo apt-get install -y gcc

# Fedora
sudo dnf install -y gcc

macOS¶

PATH reordering after shell startup¶

macOS runs /usr/libexec/path_helper from /etc/zshenv before your ~/.zshenv, which can move system paths ahead of user-defined paths (e.g., Homebrew). The dotfiles handle this by prepending user paths ($HOME/.local/bin, $HOME/bin) in ~/.zshenv after the system runs.

If a Homebrew-installed tool isn't found, check echo $PATH — system paths may have been inserted before Homebrew's prefix. Starting a new shell usually resolves this.

just zsh completions¶

just uses clap's dynamic completion: the completion function calls the just binary at runtime with special env vars to discover recipes. When tab-completion misbehaves, these are the diagnostic commands.

See the completion function:

JUST_COMPLETE=zsh just

Simulate a tab-press manually:

_CLAP_IFS=$'\n' _CLAP_COMPLETE_INDEX=3 JUST_COMPLETE=zsh just -- just -f "$HOME/Justfile" ''

• _CLAP_COMPLETE_INDEX — 0-based index of the word being completed
• just -- — everything after -- is the command line as zsh sees it
• The empty '' at the end represents the word the cursor is on

Check if the completion function is loaded:

zsh -ic 'which _just'

Clear stale completion cache (e.g. after renaming modules):

rm ~/.zcompdump* && exec zsh

Gotchas¶

• Tilde in -f breaks completions. zsh passes literal ~/Justfile to the completion engine, and just doesn't expand ~. Use $HOME/Justfile in aliases instead.
• Module renames need a fresh shell. zsh caches completions in ~/.zcompdump*. Delete the cache and restart zsh after renaming modules.