Troubleshooting

This page covers common issues you might encounter during setup and how to resolve them.

Installation Issues

Script exits immediately with 'This script is macOS-only'

This error occurs when running the setup script on a non-macOS system.Cause: The script detected the operating system is not Darwin (macOS).Solution: This setup is designed exclusively for macOS. If you’re on macOS and seeing this error, your system may have an unusual configuration. Verify with:

uname -s

This should return Darwin. If it doesn’t, contact support.

Error: 'Config path already exists and is not a git repo'

This happens when ~/.config exists but wasn’t created by this setup script.Cause: The ~/.config directory exists but is not a git repository.Solution:

Back up your existing config directory:
```
mv ~/.config ~/.config.backup
```
Re-run the setup script:
```
./setup.sh
```
Manually merge any important files from ~/.config.backup if needed.

Brewfile not found in current directory

The script can’t locate the Brewfile needed for package installation.Cause: The config repository was cloned but doesn’t contain a Brewfile, or the directory structure is unexpected.Solution:

Verify the Brewfile exists:
```
ls -la ~/.config/Brewfile
```

If missing, ensure the repository cloned correctly:

cd ~/.config
git status
git pull origin main

Re-run the setup script.

Xcode Command Line Tools

Xcode CLT installation prompt doesn't appear

The GUI prompt for installing Command Line Tools fails to show.Cause: The system may already have CLT partially installed, or the installation mechanism is blocked.Solution:Try installing manually:

xcode-select --install

If that fails, install from Xcode preferences:

Download Xcode from the Mac App Store
Open Xcode > Settings > Locations
Select a Command Line Tools version from the dropdown

'xcode-select: error: tool 'xcodebuild' requires Xcode'

Some tools require the full Xcode installation, not just Command Line Tools.Cause: Certain development workflows require the complete Xcode IDE.Solution:Install Xcode from the Mac App Store (included in Brewfile as mas "Xcode"), then run:

sudo xcodebuild -license accept

Script says to re-run after CLT installation, but nothing happens

After the CLT GUI installer completes, re-running the script doesn’t progress.Cause: The installation may not have completed successfully, or the path isn’t properly set.Solution:Verify installation:

xcode-select -p

Should return /Library/Developer/CommandLineTools or similar. If it returns an error, the installation failed. Try:

sudo rm -rf /Library/Developer/CommandLineTools
xcode-select --install

Homebrew Issues

brew command not found after installation

Homebrew installed but the brew command isn’t available.Cause: Homebrew’s bin directory isn’t in your shell’s PATH.Solution:Add Homebrew to your PATH by running:

eval "$(/opt/homebrew/bin/brew shellenv)"

For Apple Silicon Macs, add this to your ~/.zprofile:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile

For Intel Macs, use /usr/local/bin/brew instead.

brew bundle fails with 'Error: Cask X is unavailable'

Some casks in the Brewfile can’t be installed.Cause: Cask name changed, removed from Homebrew, or requires specific macOS version.Solution:

Update Homebrew:
```
brew update
```
Search for the correct cask name:
```
brew search <package-name>
```
Edit the Brewfile to use the correct name or remove unavailable casks:
```
nano ~/.config/Brewfile
```
Re-run brew bundle:
```
cd ~/.config
brew bundle
```

mas fails to install App Store apps

Mac App Store installations fail with authentication errors.Cause: Not signed into the Mac App Store, or apps require purchase.Solution:

Sign into the Mac App Store:
- Open App Store.app
- Sign in with your Apple ID
Verify you own the apps listed in the Brewfile (Xcode is free, but Logic Pro, Final Cut Pro, etc. require purchase)
Try installing manually first:
```
mas install 497799835  # Xcode
```
If specific apps fail, comment them out in the Brewfile temporarily.

brew bundle takes extremely long or hangs

Package installation appears stuck or takes hours.Cause: Large applications (Xcode is 10+ GB), slow network, or failed downloads.Solution:

Check network connectivity
Run brew bundle with verbose output:
```
cd ~/.config
brew bundle --verbose
```
For large App Store apps, install them manually via App Store.app first
Cancel and restart if truly hung (Ctrl+C, then re-run)

Permission Issues

Permission denied when creating symlinks

The script fails when trying to create symbolic links in the home directory.Cause: File permissions prevent overwriting existing files, or target files are immutable.Solution:Check if files are locked:

ls -lO ~/ | grep -E 'uchg|schg'

Unlock files if needed:

chflags nouchg ~/.zshrc  # Example for specific file

Then re-run the setup script.

Touch ID configuration fails even with sudo

Enabling Touch ID for sudo doesn’t work despite entering password.Cause: Template file missing, System Integrity Protection (SIP) restrictions, or sed command issues.Solution:

Verify the template exists:
```
ls -la /etc/pam.d/sudo_local.template
```
If missing, this feature is not available on your macOS version (requires macOS Sonoma or later)

Manually create /etc/pam.d/sudo_local:

sudo nano /etc/pam.d/sudo_local

Add this line:

auth       sufficient     pam_tid.so

Test with:

sudo -k
sudo echo "test"  # Should prompt for Touch ID

Operation not permitted errors on /usr/local

Cannot write to /usr/local during Homebrew installation.Cause: System Integrity Protection (SIP) or incorrect ownership.Solution:Fix ownership:

sudo chown -R $(whoami):admin /usr/local

On Apple Silicon Macs, Homebrew uses /opt/homebrew instead, which shouldn’t have this issue.

Git and Repository Issues

git clone fails with authentication error

Cannot clone the config repository from GitHub.Cause: Network issues, GitHub authentication problems, or repository is private.Solution:

Test GitHub connectivity:
```
ssh -T [email protected]
```

Try HTTPS instead of SSH:

git clone https://github.com/mac9sb/config.git ~/.config

If repository is private, ensure you have access and are authenticated with GitHub

Symlinks point to wrong location after repository move

Dotfiles are broken symlinks after moving or renaming ~/.config.Cause: Absolute symlinks that break when the source moves.Solution:Re-run the symlink creation part:

for file in ~/.config/.*; do
  [ -f "$file" ] || continue
  filename="$(basename "$file")"
  case "$filename" in
    .|..|.git) continue ;;
    *) ln -sf "$file" ~/ ;;
  esac
done

General Troubleshooting

How do I run the script again after fixing issues?

The script is designed to be idempotent - safe to run multiple times.Solution:Simply run:

cd ~/.config
./setup.sh

The script checks if each step is already done and skips completed steps.

How do I see detailed error messages?

Need more verbose output for debugging.Solution:Run with bash’s trace mode:

bash -x ./setup.sh

This prints each command before executing it.

Can I skip certain parts of the setup?

Want to run only specific setup steps.Solution:Comment out unwanted function calls in setup.sh:

# log "Starting macOS setup"
# ensure_config_repo
# symlink_home_dotfiles
# install_xcode_clt
# enable_touchid_for_sudo  # Skip this
install_brew_if_missing
brew_bundle
# log "Done ✅"

Or call individual functions:

source setup.sh
brew_bundle  # Run only this function

Getting Started

Configuration

Setup

Reference

Installation Issues

Xcode Command Line Tools

Homebrew Issues

Permission Issues

Git and Repository Issues

General Troubleshooting

Build docs developers (and LLMs) love

Getting Started

Configuration

Setup

Reference

​Installation Issues

​Xcode Command Line Tools

​Homebrew Issues

​Permission Issues

​Git and Repository Issues

​General Troubleshooting

Build docs developers (and LLMs) love

Installation Issues

Xcode Command Line Tools

Homebrew Issues

Permission Issues

Git and Repository Issues

General Troubleshooting