> ## Documentation Index
> Fetch the complete documentation index at: https://orchard.andrewshawcare.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot common Orchard provisioning problems

> Solutions for the most frequent problems you may encounter when running Orchard, including permission errors, failed installs, and Dock or App Store issues.

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.

<AccordionGroup>
  <Accordion title="Script fails with 'permission denied'" icon="lock">
    **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`:

    ```bash theme={null}
    chmod +x provision.sh
    ```

    To fix an individual module's install script (replace `<module>` with the module directory name):

    ```bash theme={null}
    chmod +x <module>/install.sh
    ```

    To make all install scripts executable at once:

    ```bash theme={null}
    chmod +x **/*.sh
    ```

    After running `chmod`, retry your original command.
  </Accordion>

  <Accordion title="Homebrew installation fails" icon="beer-mug-empty">
    **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.

    <Note>
      You do not need to install the Command Line Developer Tools manually. macOS will prompt you during the first run if they are needed.
    </Note>
  </Accordion>

  <Accordion title="A cask app fails to install" icon="window">
    **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](https://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:

    ```bash theme={null}
    brew list --cask <cask-name>
    ```

    <Warning>
      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.
    </Warning>
  </Accordion>

  <Accordion title="Mac App Store installs fail" icon="bag-shopping">
    **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.
  </Accordion>

  <Accordion title="provision.sh stops mid-run" icon="circle-stop">
    **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`.

    <Tip>
      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.
    </Tip>
  </Accordion>

  <Accordion title="Dock changes don't appear" icon="dock-to-bottom">
    **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:

    ```bash theme={null}
    killall Dock
    ```
  </Accordion>

  <Accordion title="Claude Code shows 'already installed' and skips" icon="circle-check">
    **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.
  </Accordion>
</AccordionGroup>