Troubleshooting

PLEASE,
PLEASE,
PLEASE brew doctor BEFORE CREATING A TICKET!

If you create a ticket please paste your brew doctor, brew --config, and brew install -v foo 2>&1 output into a Gist with your ticket.

Thank you!

1) Check for Common Issues

• brew update — then try again.
• brew doctor — the doctor diagnoses common issues.
• Try using the old environment, e.g. brew install --env=std graphviz.
• If you’re installing something Java-related, maybe you need the Java Developer Update?
• Check that Xcode and/or the “Command Line Tools for Xcode” (CLT) are up to date*
• If things fail with permissions errors you should check the permissions in /usr/local. If you’re unsure what to do, you can:

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

But really you should know what you’re doing.

• Read through the Common Issues page

* _{brew --config will list these versions. If you have Xcode installed, check the App Store for upgrades and in Preferences for CLT upgrades. If you only have the CLT installed, then check Apple Connect.}

Listen to Dr. Brew

• Update your Xcode and Command Line Tools for Xcode! Make sure that Xcode is up-to-date in the App Store. Check the CLT package is up-to-date (either via Xcode, Preferences or at Apple Connect).
• If brew doctor warns about unbrewed dylibs, these seriously cause build trouble. Yes, we know it’s hard to know what to do with this warning. But it’s hard to advise!
• If brew doctor tells to reinstall Xcode. If you have Xcode 4.3 or later, and clang --version returns an outdated version, but xcrun clang --version returns a newer. Then you'll need to reinstall Command Line Tools. Uninstall using remove_CLI_tools.sh script, reopen Xcode and you should be able to install Command Line Tools again. Finally, clang --version should show the correct version.

2) File a Ticket for the Bug

We’ll fix the bug if you ticket it. In the following instructions replace $FORMULA with the name of the formula that failed to build.

1. Create a new ticket. If the formula comes from another tap, like josegonzalez/php or homebrew/dupes, please create a ticket there;
2. Title it “$FORMULA failed to build on 10.x”, where 10.x is your version of MacOS;
3. Create a new gist, and add (in the same gist!) the following:

• The output from HOMEBREW_MAKE_JOBS=1 VERBOSE=1 brew install $FORMULA 2>&1 or brew install -v $FORMULA 2>&1
• The contents of the largest numbered log in ~/Library/Logs/Homebrew/$FORMULA, for example: 03.make;
• The output from brew doctor;

4. Link to the gist in your ticket. Be sure to post the https: link from the browser bar and not the git: link.

Thank you!