Troubleshooting¶

Solutions to common issues with this dotfiles setup.

[!TIP] Run mise run doctor first—it can automatically detect many common configuration issues.

Diagnostic Flowchart¶

flowchart TD
    A[Something isn't working] --> B{Fresh install?}
    B -->|Yes| C{mise available?}
    B -->|No| D{What broke?}
    C -->|No| E["Restart shell: exec \$SHELL -l"]
    C -->|Yes| F["Run: mise run doctor"]
    D --> G{Shell startup?}
    D --> H{Missing tool?}
    D --> I{WSL-specific?}
    G -->|Slow| J["Run: mise run profile"]
    G -->|Error| K["Check syntax: zsh -n ~/.zshrc OR bash -n ~/.bashrc"]
    H --> L["Run: mise install"]
    I --> M[See WSL-Specific Issues below]
    F --> N{Errors found?}
    N -->|Yes| O["Run: mise run install"]
    N -->|No| P[Check specific section below]

Fresh Install Issues¶

Issue: Bootstrap "hangs" or waits indefinitely¶

Symptoms: The install script stops and doesn't proceed.

Cause: The script is interactive and might be waiting for your confirmation (e.g., "Continue? [y/N]") or for you to generate keys.

Fix: Ensure you are running it in an interactive terminal.

Issue: "mise: command not found"¶

Symptoms: After running bootstrap, mise commands don't work.

Cause: Mise was installed but shell hasn't been restarted.

Fix:

# Restart your shell
exec "$SHELL" -l

# Or source mise manually (choose your shell)
eval "$(~/.local/bin/mise activate zsh)"   # zsh
eval "$(~/.local/bin/mise activate bash)"  # bash

Prevention: Always restart your shell after initial install.

Issue: mise ERROR no task install found¶

Symptoms: Bootstrap reaches install, then fails with: no task install found, but a non-executable file exists at .../mise-tasks/install

Cause: Task shim file permissions are incorrect in local checkout (commonly caused by cross-device sync/filesystem mode drift; git core.filemode=false can hide this from git status).

Fix:

cd "$DOTFILES_DIR"
git pull --rebase

# Repair execute-bit drift across shell-based tasks
bash scripts/check-shell-script-modes --path mise-tasks --repair

# Optional: confirm environment health and warnings
dots doctor

# Retry bootstrap/install after pulling permission fixes
./scripts/bootstrap
# or
mise run install

Root cause: On WSL2, git often defaults to core.fileMode=false, which prevents it from tracking or restoring execute bits on checkout. Since the dotfiles repo lives on ext4, this setting is unnecessary.

Prevention: - dots doctor now auto-fixes core.fileMode=false when detected - scripts/bootstrap sets core.fileMode=true on fresh clones - Run mise run lint (checks shell script executable bits in mise-tasks/) - Run dots doctor after syncing to a new device

Issue: dots update skips system package updates (sudo would prompt)¶

Symptoms: dots update completes, but prints a warning that system package updates were skipped to avoid a password prompt.

Cause: By default, dots update avoids interactive sudo prompts and skips privileged package-manager upgrade steps when non-interactive sudo is unavailable.

Fix / Intentionally include system package upgrades:

dots update --system-updates

Explicitly skip package-manager upgrades:

dots update --skip-system-updates

Also note: - If gh is already mise-managed, dots update skips the package-manager gh upgrade step automatically - Use dots update --dry-run to see whether the step will run or be skipped (and why)

Issue: dots update refuses to run because the dotfiles repo is dirty¶

Symptoms: dots update exits with a message about unstaged changes.

Cause: The default update flow keeps a clean-worktree guard to avoid rebase/apply conflicts and surprise local changes.

Fix options:

# Recommended: stash automatically and restore after update
dots update --auto-stash

# Advanced: proceed without stashing (you handle conflicts/risk)
dots update --allow-dirty

Notes: - --auto-stash restores changes at the end; if restore conflicts, dots update prints recovery commands. - --auto-stash and --allow-dirty are mutually exclusive.

Issue: dots update says another update is already running¶

Symptoms: dots update fails fast with a lock-file message and suggests --wait-for-lock.

Cause: An update lock now prevents concurrent runs from multiple shells/devices from overlapping.

Fix:

# Wait for the existing update to finish
dots update --wait-for-lock

Notes: - The lock lives in your runtime temp dir (for example /tmp/dots-update.lock). - If a previous update crashed, simply re-run; the lock is advisory and tied to the process/file descriptor.

Issue: dots update skips plugin/network steps (fast/offline modes)¶

Symptoms: Update summary shows steps like git pull, plugin syncs, or system package updates as skipped.

Cause: - --offline skips all networked steps - --fast skips plugin updates and system package updates - Default mode may also skip system package updates if sudo would prompt

Debug / inspect planned behavior:

dots update --dry-run

Full run examples:

# Include optional steps (still non-interactive for sudo unless forced)
dots update --full

# Include privileged package upgrades too (may prompt for sudo)
dots update --full --system-updates

Issue: Need to repair common local drift safely without running install/update¶

Symptoms: You want to repair task execute bits or agent symlinks without running a full install/update.

Fix:

dots doctor --fix

What --fix will do (safe/local only): - Repair shell script execute-bit drift under mise-tasks/ - Repair CLAUDE.md / GEMINI.md symlinks to AGENTS.md - Create a few safe local directories if missing

What it will not do: - sudo package installs - network/plugin updates - shell/login-shell changes

Issue: mise reports "Config files ... are not trusted" when cd into a project¶

Symptoms: Changing into a repo with .mise.toml prints an untrusted config error.

Cause: mise trust is path-based and per-project. A sibling directory is not auto-trusted just because another repo under the same parent is trusted.

Fix:

# Trust this project's config
mise trust -C ~/path/to/project

# Or ignore this project's config in the future
mise trust --ignore -C ~/path/to/project

Zsh behavior in this dotfiles repo: - On first entry into an untrusted repo, the shell shows one prompt: - [t]rust -> runs mise trust -y -C <repo> - [i]gnore -> runs mise trust --ignore -y -C <repo> - [s]kip (or Enter) -> no change, prints manual commands - The prompt is shown once per directory per shell session to avoid repeated noise.

Non-interactive shells: No prompt is shown; the shell prints the exact commands to run manually.

Issue: Install fails at chsh / can't change default shell¶

Symptoms: mise run install fails near the end with errors about chsh, sudo, or a missing/empty user.

Cause: Changing the default login shell is environment-specific and can fail in non-interactive environments (CI/containers), or when sudo/user accounts aren't available. Also, in server mode this project keeps the current shell by default.

Current behavior: - Interactive installs now prompt before running chsh. - If the system login shell is already zsh, the prompt is skipped. - If install cannot confirm the account shell from system records, reruns keep prompting instead of trusting the current $SHELL.

Fix:

# Re-run install and choose "n" at the shell-change prompt
mise run install

# Optional: change manually on workstations
chsh -s "$(command -v zsh)"

Automation note: In CI/non-interactive environments, shell changes are skipped automatically. You can also force skip with DOTFILES_SKIP_CHSH=1.

Issue: Install fails during doctor on minimal systems/containers¶

Symptoms: mise run install fails at the very end during mise run doctor, often due to missing optional packages (e.g., tmux).

Cause: doctor is a health check that assumes a fairly complete environment. On minimal images/containers, it may report errors.

Fix:

# Skip running doctor as part of install
DOTFILES_SKIP_DOCTOR=1 mise run install

# Or run the health check separately after installing missing dependencies
mise run doctor

Note: In CI/non-interactive environments, the install task skips running doctor automatically.

Issue: Dotfiles not applying¶

Symptoms: Running mise run install or chezmoi apply doesn't update files.

Cause: Chezmoi config needs re-initialization or file already exists.

Fix:

# Re-init chezmoi (handles template changes)
chezmoi init --source $DOTFILES_DIR --apply --force

# Or check diff first
chezmoi diff --source $DOTFILES_DIR

Prevention: Use dots cz reinit to re-init when you see "config file template has changed" warning.

Issue: Unexpected repository files appear directly in ~¶

Symptoms: Files like ~/CODE_OF_CONDUCT.md, ~/tests, ~/ansible, or ~/config/site appear after install/update.

Cause: Those paths were not excluded by .chezmoiignore, so chezmoi treated repo artifacts as managed home files.

Fix:

# 1) Pull latest ignore patterns
cd "$DOTFILES_DIR"
git pull --rebase

# 2) Remove existing artifacts from home (safe paths only)
rm -rf ~/CODE_OF_CONDUCT.md ~/CONTRIBUTING.md ~/DNS-FIX-SUMMARY.md ~/GEMINI.md ~/SECURITY.md
rm -rf ~/cliff.toml ~/mise-server.toml ~/ansible ~/config ~/examples ~/mise-profiles ~/mkdir ~/tests

# 3) Re-apply dotfiles
mise run install

Prevention:

# Verify unwanted root-level paths are not managed
chezmoi managed | rg '^(CODE_OF_CONDUCT\.md|CONTRIBUTING\.md|DNS-FIX-SUMMARY\.md|GEMINI\.md|SECURITY\.md|cliff\.toml|mise-server\.toml|ansible|config|examples|mise-profiles|mkdir|tests)(/|$)'

Issue: Chezmoi keeps asking for email/name¶

Symptoms: Every time you run chezmoi init or update, it prompts for email. Cause: older chezmoi.toml.tmpl didn't check for existing values. Fix: Update to latest template which uses hasKey logic.

chezmoi init --source $DOTFILES_DIR --apply

Issue: "antidote: command not found"¶

Symptoms: Zsh loads but with errors about antidote.

Cause: Antidote wasn't installed or installation failed.

Fix:

# Install Antidote manually
git clone --depth=1 https://github.com/mattmc3/antidote.git ~/.antidote

# Restart shell
exec zsh

Issue: "~/.secrets missing" warning from doctor¶

Symptoms: mise run doctor shows a warning about missing secrets file.

Cause: Secrets file hasn't been created yet.

# Option A: Manual (unencrypted)
cp ~/repos/dotfiles/dot_secrets.example ~/.secrets
nvim ~/.secrets

# Option B: Encrypted (recommended)
mise run setup-secrets

See Secrets Management for details.

Shell Issues¶

Issue: Enter key behaves strangely in Bash (Ctrl+C needed, output redraw glitches)¶

Symptoms: Commands do not execute normally, output appears in odd order, prompt redraw is broken.

Cause: Enter (Ctrl-M) was rebound in Bash using bind -x, replacing Readline's default accept-line.

Fix:

# Restore default Enter handling for current session
bind '"\C-m": accept-line'
stty sane
reset
exec bash -li

Prevention: - Do not bind Enter in Bash. - Keep shell-specific keybinding tricks in zsh only.

Issue: Default hostname% prompt after reboot (no theme/autocomplete)¶

Symptoms: Prompt shows Jeremy-Surface% (or similar), no Powerlevel10k styling, autosuggestions/completions feel missing.

Cause: Static plugin bundle (~/.zsh_plugins.zsh) is missing or empty, so plugin/theme code never loads.

Fix:

# 1. Verify bundle is present and non-empty
ls -l ~/.zsh_plugins.zsh
wc -c ~/.zsh_plugins.zsh

# 2. Rebuild bundle and compile cache
source ~/.antidote/antidote.zsh
antidote bundle < ~/.zsh_plugins.txt > ~/.zsh_plugins.zsh
zcompile ~/.zsh_plugins.zsh

# 3. Reload shell
exec zsh

Prevention:

# Health check now warns about empty/missing plugin bundle
mise run doctor

Issue: Shell startup is slow (>2s)¶

Symptoms: Opening a new terminal takes several seconds.

Cause: Usually one of: 1. Too many plugins loading 2. Slow network call (atuin sync, zoxide init) 3. Large history file

Fix:

# Profile startup time
time zsh -i -c exit

# For detailed timing
zmodload zsh/zprof
# (add to top of .zshrc, run `zprof` after shell loads)

Common Fixes:

# Defer atuin sync
# In ~/.zshrc.local:
export ATUIN_SYNC_FREQUENCY=0  # Disable auto-sync

# Reduce history size if very large
# In ~/.zshrc, lower HISTSIZE

Issue: Powerlevel10k not loading / ugly prompt¶

Symptoms: Plain prompt, no icons, or gibberish characters.

Cause: Missing Nerd Font or p10k not configured.

Fix:

# 1. Install a Nerd Font (e.g., MesloLGS NF)
# Download from: https://www.nerdfonts.com/

# 2. Set your terminal to use the Nerd Font

# 3. Reconfigure p10k
p10k configure

Issue: Antidote plugins not loading¶

Symptoms: Plugins like zsh-autosuggestions not working.

Cause: Plugin list not being loaded or antidote cache stale.

Fix:

# Clear antidote cache
rm -rf ~/.cache/antidote

# Rebuild plugins
antidote load ~/.zsh_plugins.txt

# Restart shell
exec zsh

Tool Issues¶

Issue: FZF Ctrl+T not showing preview¶

Symptoms: File list appears but no preview pane.

Cause: bat not installed or FZF_CTRL_T_OPTS not set.

Fix:

# Check bat is installed
command -v bat

# If missing, install it
mise install

# Check env var is set
echo $FZF_CTRL_T_OPTS

Issue: zoxide not jumping to directories¶

Symptoms: z command says "no match found".

Cause: zoxide hasn't learned your directories yet.

Fix:

# Check zoxide database
zoxide query -l

# If empty, navigate to directories normally first
cd ~/projects
cd ~/dotfiles
cd /etc

# Now zoxide will remember them
z proj  # Should work

Issue: Atuin not syncing history¶

Symptoms: History not appearing on other machines.

Cause: Not logged in or sync disabled.

Fix:

# Check login status
atuin status

# Login if needed
atuin login

# Force sync
atuin sync

WSL-Specific Issues¶

Issue: Windows commands not found (explorer.exe, etc.)¶

Symptoms: open alias doesn't work, can't run Windows executables.

Cause: WSL interop not working or path not set.

Fix:

# Check interop is enabled
cat /proc/sys/fs/binfmt_misc/WSLInterop

# If missing, in Windows PowerShell (admin):
wsl --shutdown
# Then restart WSL

# Ensure Windows PATH is in WSL path
# In /etc/wsl.conf:
[interop]
appendWindowsPath = true

Issue: DNS resolution failures ("Temporary failure in name resolution")¶

Symptoms: - ping google.com fails but ping 8.8.8.8 works - Internet works after WSL restart but breaks later - Network changes (VPN, sleep/wake) break DNS

Cause: Configuration conflict between WSL's DNS management and systemd-resolved.

Quick Fix:

# Automated fix
mise run fix:wsl-dns

# Then restart WSL (from PowerShell)
wsl --shutdown

Detailed Diagnosis & Solutions: See WSL DNS Quick Fix Guide

Prevention: Run mise run doctor regularly to detect DNS configuration issues.

Issue: Slow file access in /mnt/c¶

Symptoms: Commands like ls or git are very slow on Windows drives.

Cause: WSL filesystem translation overhead.

Fix: Work from your Linux home directory instead:

# Move projects to Linux filesystem
mv /mnt/c/Users/you/projects ~/projects

# Much faster!

Issue: WSL shuts down unexpectedly / won't stay running¶

Symptoms: WSL terminates after periods of inactivity, SSH sessions drop.

Cause: WSL 2 has an idle timeout (default 60 seconds after last process exits).

Fix (Windows 11 only): Edit or create %USERPROFILE%\.wslconfig:

[wsl2]
vmIdleTimeout=-1

Then restart WSL:

wsl --shutdown
wsl

[!NOTE] This setting is only available on Windows 11. The dotfiles provisioning script (mise-tasks/setup/provision/windows/install.ps1) will copy a pre-configured .wslconfig if one doesn't exist.

Issue: Clipboard not working¶

Symptoms: Can't copy/paste between terminal and Windows.

Cause: Missing Windows clipboard integration.

Fix: Add to ~/.zshrc.local:

if grep -q "Microsoft" /proc/version 2>/dev/null; then
    alias pbcopy="clip.exe"
    alias pbpaste="powershell.exe -command 'Get-Clipboard'"
fi

Tmux Issues¶

Issue: TPM plugins not installing¶

Symptoms: Tmux works but plugins (continuum, resurrect) don't load.

Cause: TPM not installed or not initialized.

Fix:

# Install TPM
git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

# In tmux, install plugins
# Press: prefix + I (capital i)
# Default prefix is Ctrl+b

Issue: Sessions not auto-restoring¶

Symptoms: After reboot, tmux doesn't restore previous session.

Cause: tmux-resurrect needs explicit save, continuum may be misconfigured.

Fix:

# Manually save session
# In tmux: prefix + Ctrl+s

# Check continuum status
# In tmux: prefix + Ctrl+s shows save time

# Verify .tmux.conf has:
set -g @continuum-restore 'on'

Issue: "resurrection file not found" on startup¶

Symptoms: When starting tmux, you see a message saying "resurrection file not found" or "no saved session".

Cause: This is normal for a first-time installation. tmux-resurrect hasn't saved a state file yet, so tmux-continuum has nothing to restore.

Fix: 1. Start tmux normally (ignore the warning). 2. Press Prefix + Ctrl-s to manually save the first state. 3. The warning will disappear on future launches.

Recovery¶

Full Reset¶

If everything is broken and you want to start fresh:

# 1. Uninstall all symlinks
mise run uninstall

# 2. Remove mise tools
rm -rf ~/.local/share/mise

# 3. Remove cached configs
rm -rf ~/.cache/antidote ~/.cache/atuin

# 4. Remove plugin manager
rm -rf ~/.antidote

# 5. Reinstall
cd ~/repos/dotfiles
./scripts/bootstrap

Rollback to Previous State¶

If a recent change broke things:

# View recent changes
cd ~/repos/dotfiles
git log --oneline -10

# Checkout previous version
git checkout HEAD~1

# Reinstall
mise run install

# Test, then if OK, reset to main
git checkout main

Error Message Quick Reference¶

Getting Help¶

If you can't find a solution here:

1. Run mise run doctor to identify issues
2. Check CI Troubleshooting for pipeline issues
3. Check tool-specific docs linked in TOOLS.md
4. Search GitHub issues for the relevant tool