Skip to main content
Most Orchard issues fall into a small number of categories: file permission problems, missing prerequisites, or state mismatches between what a script expects and what is already on your machine. The entries below cover the issues you are most likely to encounter and how to resolve each one.
Cause: The shell scripts in Orchard must be executable. If you cloned the repository and the execute bit was not preserved, macOS will refuse to run the scripts.Fix: Make the script executable before running it.To fix provision.sh:
chmod +x provision.sh
To fix an individual module’s install script (replace <module> with the module directory name):
chmod +x <module>/install.sh
To make all install scripts executable at once:
chmod +x **/*.sh
After running chmod, retry your original command.
Cause: The brew module downloads and runs the official Homebrew installer from the internet. If your machine has no internet access, or if Apple’s Command Line Developer Tools are not installed, the installer will fail.Fix:
  1. Confirm you have an active internet connection.
  2. If prompted by macOS to install the Command Line Developer Tools, click Install and wait for it to complete. macOS shows this prompt automatically when the installer detects the tools are missing.
  3. Re-run ./provision.sh once the tools are installed.
You do not need to install the Command Line Developer Tools manually. macOS will prompt you during the first run if they are needed.
Cause: There are two common reasons a cask installation fails. The app may already be installed on your machine from a source other than Homebrew (such as a manual download from the vendor’s website), or the cask name in your cask-packages/package-list.bash file may be incorrect.Fix:
  1. Check that the cask name is correct at formulae.brew.sh/cask.
  2. If the app is already installed from a non-Homebrew source, either uninstall it first and re-run ./provision.sh, or remove it from cask-packages/package-list.bash if you do not need Homebrew to manage it.
To check whether Homebrew already knows about the app:
brew list --cask <cask-name>
Uninstalling an app before re-running provision.sh will delete the app and any data it stores inside its own bundle. Back up any important application data before uninstalling.
Cause: The mac-app-store module uses mas to install apps from the Mac App Store. mas requires you to be signed in to the Mac App Store, and it can only install apps that you have previously purchased or downloaded (including free apps that require acceptance of terms).Fix:
  1. Open the App Store application.
  2. Sign in with your Apple ID under Account in the sidebar.
  3. Re-run ./provision.sh.
If a specific app still fails after signing in, search for it manually in the App Store to confirm your Apple ID has access to it.
Cause: Orchard’s scripts run with set -euo pipefail, which means the script stops immediately when any command returns a non-zero exit code. This is intentional — it prevents a failure in one module from silently causing incorrect behaviour in later modules.Fix:
  1. Read the error message printed before the script stopped. It will identify which command failed and why.
  2. Resolve the underlying issue (for example, connect to the internet, sign in to the App Store, or fix a misconfigured package name).
  3. Re-run ./provision.sh.
Re-running provision.sh from the start is always safe. Homebrew skips packages it has already installed, and modules like claude-code check for an existing installation before taking any action. You will not end up with duplicate installations.
Cause: The dock module applies changes using defaults write and then restarts the Dock process with killall Dock. In some cases — particularly if you ran provision.sh while another operation was restarting the Dock — the changes may not have taken effect.Fix: Restart your Mac. A full restart ensures the Dock process starts fresh and reads the updated preferences.If you want to manually restart the Dock without rebooting:
killall Dock
Cause: This is expected behaviour, not an error. The claude-code module checks whether claude is already present in your PATH before attempting to install it. If it finds an existing installation, it exits immediately without making any changes.Fix: No action is required. If you want to update Claude Code to a newer version, do so through Claude Code’s own update mechanism rather than through Orchard.