When something's not right

Troubleshooting: the calm fixes for the usual snags.

Most "it's broken" moments after a fresh install are one of a dozen known things — a permission macOS won't let a script grant, a step that needs a restart, a tool that just needs re-applying. Here's the map, roughly in the order you'll hit them.

#Quick triage

#Install & bootstrap

Homebrew says the Xcode license is not accepted

Fix the first error, then re-run bootstrap-mac.sh. If Homebrew stops at the Xcode license check, the later gh: command not found or chezmoi: command not found messages are just follow-on errors because those tools never installed.

$ sudo xcodebuild -license accept
$ bash -c "$(curl -fsSL https://raw.githubusercontent.com/jasondockery/groundwork/main/bootstrap-mac.sh)"

Homebrew also requires the current macOS user to be an Administrator. If sudo -v fails, add that user as an admin first or run the install from an admin account.

You cannot find Xcode after setup

Groundwork always handles Apple's Command Line Tools, not full Xcode by default. If xcode-select -p prints /Library/Developer/CommandLineTools, the terminal build layer is present. Full Xcode installs only when you answer yes to the Xcode setup prompt, and even then the App Store install can fail if you are not signed in or Xcode has never been obtained on that Apple Account. If you need it, get Xcode from the Mac App Store, open it once, then run sudo xcode-select -s /Applications/Xcode.app/Contents/Developer.

Bootstrap URL returns 404

A 404 from raw.githubusercontent.com usually means the branch name, path, or URL is wrong, or GitHub is temporarily unreachable. The public bootstrap URL should work without GitHub login. Copy it from the README again, or open the URL in a browser to see the actual GitHub error.

Homebrew skipped or failed a package

On a brand-new or beta macOS, Homebrew sometimes has no pre-built bottle for a formula and either builds it slowly from source or skips it. brew bundle deliberately continues past failures, so the install finishes — you just re-run the stragglers:

$ brew bundle --file=~/.config/homebrew/Brewfile   # retry everything (idempotent)
$ brew install <formula>                            # or just the one that failed
$ brew doctor                                       # diagnose a broken install

Downloads fail with curl: (92) or the fetch stalls

Repeated HTTP/2 stream was not closed cleanly: PROTOCOL_ERROR failures across several vendors usually point to the connection — a VPN, proxy, travel router, or guest Wi-Fi — though a vendor outage or a local ~/.curlrc can look the same; it is rarely a broken setup. When downloads fail, the update re-fetches just the failed ones, one at a time with backoff, and leaves everything that succeeded alone. If a large parallel fetch stalls after a download error, pressing CtrlC and re-running update-all is safe in the sense that installed packages stay installed and completed downloads are normally cached — but the rerun repeats the normal update phases rather than resuming mid-fetch, so skim the final output before retrying.

Homebrew warns: "The following taps are not trusted"

Homebrew now requires you to explicitly trust third-party taps before it will use their formulae and casks — a supply-chain protection, and the taps it lists are ones you (or a tool you ran) added; Groundwork adds none. Ignore the warning and those taps stay inert. To keep using something from one, prefer trusting just the formulae you actually use over whole-tap trust, which also covers everything the tap publishes in the future:

$ brew trust --formula hashicorp/tap/terraform   # narrow: one formula
$ brew untap someuser/sometap                     # or drop a tap you no longer use

A Python tool tries to build SciPy or asks for gfortran

Global Python tools intentionally use a proven Python version, not the newest Python release. Heavy dependencies such as NumPy and SciPy need mature wheel coverage; when a tool runs on a too-new Python, uv can fall back to a slow source build and fail on a normal Mac because no Fortran compiler is installed. Keep the global tool Python on the Groundwork-managed version, and choose newer Python versions per project with mise use python@... only when that project needs them.

Aider crashes with audioop or pyaudioop

That means Aider was installed into a too-new Python tool environment. Groundwork keeps Aider's isolated uv runtime on Python 3.12 for now, because Python 3.13 removed audioop and Aider's voice dependency path can still import it on startup. The global mise Python remains 3.13; mise also provisions 3.12 so this tool pin is declared. Repair it with:

$ uv tool install --python 3.12 --reinstall aider-chat
$ aider --version

"command not found" right after install

Your current shell started before the tool existed. Reload it — exec zsh — or open a new terminal tab. Still missing? Confirm Homebrew actually installed it with brew list <name>, and that Homebrew is on your path with which brew (should be /opt/homebrew/bin/brew).

Restore the pre-Groundwork snapshot

Use this when the setup applied successfully but the person decides they do not like the opinionated defaults. The helper runs the latest first-run backup's restore script and asks for confirmation.

$ groundwork-restore
# or inspect the backup first:
$ open ~/.local/state/groundwork/backups/latest

The restore is intentionally limited to the files and macOS defaults this repo snapshots. It does not uninstall software, remove Homebrew packages, undo app permissions, or replace a full system backup.

Old configs are competing with the setup

On a Mac that has been configured by hand for years, old editor, tmux, shell completion, or plugin state can compete with this setup. During chezmoi init, answer yes to the reset prompt for a clean start. The reset moves known conflict zones to ~/.local/state/groundwork/reset/latest before applying Groundwork.

chezmoi warns: "config file template has changed, run chezmoi init"

This appears after a bare chezmoi update when Groundwork's setup template changed. Running chezmoi init again is not starting over: every answer you already gave is kept (the questions are ask-once), so it regenerates the config from your existing answers. If no new question was added, it returns silently — that is success, not a no-op: the config was rebuilt with your saved answers and nothing was reinstalled. update-all and chezmoi update --init handle this automatically, which is why they are the recommended forms:

$ chezmoi init     # regenerate from existing answers (silent = success)
$ chezmoi apply    # apply with the refreshed config

To change a setting (not just regenerate), use groundwork-configure: it shows your current answers, changes only the one you pick, previews the diff, and applies after you confirm. Plain chezmoi init never asks what to change, and chezmoi init --prompt replays the entire interview using template defaults — which can silently reset answers — so it is an advanced/debugging path, not the way to tweak one setting.

Windows & WSL: scripts fail with bad interpreter: ^M

That ^M is a Windows carriage return: the clone was made with Git for Windows converting files to CRLF line endings, which breaks shell scripts and chezmoi templates the moment WSL runs them. Groundwork ships a .gitattributes that forces LF, so a fresh clone made inside WSL checks out correctly. If you hit this, re-clone from a WSL terminal, and tell Git to never introduce CRLF again:

$ git config --global core.autocrlf input
$ git clone https://github.com/jasondockery/groundwork.git

A clone made before the fix stays broken even after git pull, because Git only rewrites the files a pull touches; everything else keeps its CRLF endings, including the chezmoi .tmpl files. Instead of re-cloning you can renormalize in place. This discards uncommitted local changes, so commit or stash first:

$ git rm --cached -r .
$ git reset --hard

#tmux

See the tmux page for what each plugin does and how saving/restoring works.

#Neovim

The first time you open nvim, LazyVim downloads and compiles its plugins — let it finish before judging anything. After that, two commands diagnose almost everything:

:Lazy            # plugin manager — press U to update, X to clean
:checkhealth     # reports missing tools (node, rg, fd…) and how to fix

If :checkhealth flags a missing command-line tool, install it with brew install <tool> — Neovim's extras lean on the same CLI tools from the Shell page (ripgrep, fd). If the editor ever gets truly wedged, it's safe to wipe its state and let it rebuild: rm -rf ~/.local/share/nvim ~/.local/state/nvim, then reopen.

#Shell & prompt

#Claude Code

#Docker

#Karabiner (keyboard)

Caps Lock → Esc/Ctrl won't work until macOS trusts Karabiner. It needs two approvals that only you can click:

After Groundwork installs or updates Homebrew casks, it reopens the always-on apps — Karabiner-Elements, Raycast, BetterDisplay, and Anybox — if any is installed but not running, because Homebrew quits an app to replace it and never relaunches it. For Karabiner that makes the menu-bar icon, driver status, and any macOS permission prompts visible instead of leaving the keyboard rule silently inactive; for the others it keeps the launcher hotkey, display presets, and bookmark shortcuts answering. If macOS shows an "open an app downloaded from the internet" prompt, approve it only when it names one of these apps from your Applications folder.

If chezmoi apply mentions .config/karabiner/karabiner.json, the usual cause is Karabiner writing device or profile metadata after Groundwork last touched the file. Current Groundwork merges the Caps Lock rule into Karabiner's existing JSON instead of replacing the whole file, so pull the latest repo and re-run chezmoi apply.

#Obsidian

#Git keeps asking for a login

This is an access problem, not a setup bug. git pull / chezmoi update can't authenticate. The usual culprit is being logged into gh as the wrong account, or using an SSH remote without the matching key/account configured. First, see who you are:

$ gh auth status                # is this the right account?
$ gh auth switch                # choose another already-authenticated account
$ gh auth login --git-protocol https
$ gh auth setup-git --hostname github.com

Groundwork itself pulls from a public HTTPS remote by default. The credential helper is still baked into the git config because most developers use GitHub for their own repos, and chezmoi manages ~/.gitconfig. SSH is still fine when the Mac's SSH config clearly maps the right key to the right GitHub account.

#Still stuck?

Two reliable fallbacks. Re-apply from the source of truth, and if that doesn't do it, ask an agent — it can read the actual error and the config together:

$ chezmoi update                # pull latest config + apply it
$ claude                        # then paste the error and ask