* Run `brew doctor` — the doctor diagnoses common issues.
* Read through the [Common Issues](Common-Issues.md) page.
* If you’re installing something Java-related, maybe you need the [Java Developer Update][] or [JDK 7][]?
* Check that **Command Line Tools for Xcode (CLT)** and/or **Xcode** are up to date.
* If things fail with permissions errors, check the permissions in `/usr/local`. If you’re unsure what to do, you can `sudo chown -R $(whoami) /usr/local`.
#### Listen to Dr. Brew
* **Update Xcode and/or Command Line Tools for Xcode!** Make sure that Xcode is up-to-date in the App Store. Check that the CLT package is up-to-date (either via Xcode, Preferences or at [Apple Developer][]).
* If `brew doctor` warns about unbrewed dylibs, be advised that they are **very likely to cause build problems**.
## Check to see if the issue has been reported
* Browse open issues on the [issue tracker](https://github.com/Homebrew/homebrew/issues) to see if someone else has already reported the same problem.
* Make sure you check issues on the correct repository. If the formula that failed to build is part of a tap, like [homebrew-science](https://github.com/Homebrew/homebrew-science) or [homebrew-dupes](https://github.com/Homebrew/homebrew-dupes), check there instead.
## Create an issue
1. [Create a new issue](https://github.com/Homebrew/homebrew/issues/new)
* Again, make sure you file the issue against the correct repository.
* If you are reporting a build failure, title it "\<formula name> failed to build on 10.x", where \<formula name> is the name of the formula that failed to build, and 10.x is the version of OS X you are using.
* Otherwise, choose a title that best describes the problem you are experiencing.
2. Upload a [Gist][] with relevant debugging information
* The simplest method is to run `brew gist-logs <formula name>`
* You can also create a [Gist][] manually. Include the following:
1. The output from `HOMEBREW_MAKE_JOBS=1 brew install -v <formula name> 2>&1`
2. The contents of the largest numbered log in `~/Library/Logs/Homebrew/<formula name>`, e.g. `03.make`
3. The output from `brew config` and `brew doctor`
* If you are reporting a bug rather than a build failure, please include `brew config`, `brew doctor`, and enough information to reliably reproduce the bug.
3. Include a link to the gist in your new issue
* Be sure to use the `https:` URL (i.e. the URL in your browser's address bar), not the `git:` URL.
