Troubleshooting

How do I fix my zsh completions?#

After installing Workbrew, zsh users may see warnings about insecure directories or errors about function definition files not being found. This happens because Workbrew manages Homebrew under the workbrew user, and zsh flags files owned by a different user as insecure. See How to fix zsh errors after installing Workbrew for instructions.

How should I add Workbrew and Homebrew to the PATH on a Device?#

Users should add eval $(/opt/workbrew/bin/brew shellenv) to their shell startup configuration. If users already have eval $(/opt/homebrew/bin/brew shellenv) in their shell startup configuration, that will also work.

How does Workbrew handle brew services?#

Workbrew will attempt to stop all existing brew services on installation. After installation, Workbrew will run all (non-root) services as the workbrew user.

I get permissions errors when running for example brew update#

You need to run brew through /opt/workbrew/bin/brew, and not /opt/homebrew/bin/brew or /usr/local/bin/brew. Please see the How should Workbrew and Homebrew be added to the PATH on a Device?.

I get permission errors when attempting to write to Homebrew's installation directories e.g. /opt/homebrew or /usr/local#

With Workbrew, the Homebrew directory is intentionally not writable by non-workbrew users. Instead, configure your tools to write to your HOME directory. See below for instructions for npm. If you need help with other tools, please contact us and we'll help.

npm install -g fails with EACCES errors#

npm install -g fails with EACCES errors because the npm global install directory isn't writable by non-workbrew users under Workbrew. Please configure npm install -g to install into your HOME directory using the following steps:

1. Create the npm global directories under HOME: mkdir -p ~/.npm-global/bin ~/.npm-global/lib 2. Configure npm to use the directories created above: npm config set prefix '~/.npm-global' 3. Add your npm global directory to PATH: export PATH="~/.npm-global/bin:$PATH" See the npm documentation for more details.

After Xcode updates, brew fails with “license not accepted”#

Some macOS updates or App Store auto updates might reset the Xcode license. Until the license is accepted again, brew commands and Workbrew Agent check-ins may fail. Console admins can remediate this by deploying the following script via their MDM:

if /usr/bin/xcrun -find xcodebuild >/dev/null 2>&1; then
  if ! /usr/bin/xcodebuild -license check >/dev/null 2>&1; then
    /usr/bin/xcodebuild -license accept
  fi
fi ```