Troubleshooting

PLEASE,
PLEASE,
PLEASE run brew update and brew doctor BEFORE CREATING AN ISSUE!

If you create an issue please paste the output of running brew doctor, brew --config and brew install -v foo 2>&1 into a Gist and provide link to aforementioned gist within your issue.

Thank you!

1) Check for Common Issues

• Run brew update — then try again.
• Run brew doctor — the doctor diagnoses common issues.
• Try using the old environment, e.g. run brew install --env=std graphviz.
• If you’re installing something Java-related, maybe you need the Java Developer Update?
• Check that Command Line Tools for Xcode (CLT) and/or Xcode 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 you 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. Upload relevant debugging information by either:
4. manually creating a new gist, and adding (in the same gist!) the following:
   1. The output from HOMEBREW_MAKE_JOBS=1 brew install -v $FORMULA 2>&1
   2. The contents of the largest numbered log in ~/Library/Logs/Homebrew/$FORMULA, for example: 03.make;
   3. The output from brew doctor;
5. or alternatively with brew gist-logs --config --doctor $FORMULA.
6. 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!