Troubleshooting

PLEASE,
PLEASE,
PLEASE brew doctor BEFORE CREATING A 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][Apple Connect]?
• 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!

2) File a Ticket for the Bug

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

1. Create a new ticket;
2. Title it “Foo failed to build on 10.x”, where 10.x is your version of MacOS;
3. Paste the output from brew. PLEASE put the output in a triple-backtick-block, like so:

```sh
Build output goes here!

4. Create a new [gist](https://gist.github.com), and add (in the same gist!) the following:
  * The largest numbered log in `~/Library/Logs/Homebrew/foo`, for example: `03.make`;
  * The output from `brew doctor`;
5. Link to the gist in your ticket. Be sure to post the `http:` link from the browser bar and not the `git:` link.

Thank you!

[Apple Connect]:http://connect.apple.com