brew/docs/Troubleshooting.md

# Troubleshooting

**Run `brew update` twice and `brew doctor` (and fix all the warnings) *before* creating an issue!**

This document will help you check for common issues and make sure your issue has not already been reported.

## Check for common issues

* Read through the [Common Issues](Common-Issues.md).

## Check to see if the issue has been reported

* Search the [Homebrew/homebrew-core issue tracker](https://github.com/Homebrew/homebrew-core/issues) to see if someone else has already reported the same issue.
* If a formula that has failed to build is part of a non-core tap or a cask is part of [homebrew/cask](https://github.com/Homebrew/homebrew-cask/issues) check those issue trackers instead.
* Search the [Homebrew discussion forum](https://github.com/homebrew/discussions/discussions) or [Discourse](https://discourse.brew.sh/) to see if any discussions have started about the issue.

## Create an issue

If your problem hasn't been solved or reported, then create an issue:

1. Upload debugging information to a [Gist](https://gist.github.com):

  * If you had a formula-related problem: run `brew gist-logs <formula>` (where `<formula>` is the name of the formula).
  * If you encountered a non-formula problem: upload the output of `brew config` and `brew doctor` to a new [Gist](https://gist.github.com).

2. Create a new issue on the [Homebrew/homebrew-core issue tracker](https://github.com/Homebrew/homebrew-core/issues/new/choose)

  * Give your issue a descriptive title which includes the formula name (if applicable) and the version of macOS or Linux you are using. For example, if a formula fails to build, title your issue "\<formula> failed to build on \<10.x>", where "\<formula>" is the name of the formula that failed to build, and "\<10.x>" is the version of macOS or Linux you are using.
  * Include the URL output by `brew gist-logs <formula>` (if applicable).
  * Include links to any additional Gists you may have created (such as for the output of `brew config` and `brew doctor`).
Import docs from wiki. Closes Homebrew/homebrew#33211. 2014-10-26 14:54:36 +00:00			`# Troubleshooting`
Troubleshooting: don't report the update issue plz 2015-08-07 12:20:37 +01:00
Update Linuxbrew references to Homebrew on Linux This is a clearer branding for us to use. Also, as part of testing this, make some fixes to Jekyll in the docs folder. Fixes #5835 2019-03-12 20:13:38 +00:00			*Run `brew update` twice and `brew doctor` (and fix all the warnings) before* creating an issue!**
restore the more forceful introduction to the Troubleshooting doc 2016-11-07 18:15:10 +00:00
			`This document will help you check for common issues and make sure your issue has not already been reported.`
Import docs from wiki. Closes Homebrew/homebrew#33211. 2014-10-26 14:54:36 +00:00
			`## Check for common issues`
revise troubleshooting doc 2016-11-06 18:15:58 +00:00
Revert "docs: use short links." This reverts commit e63a2ee8de12f0f938f6a95cdb9763dbe0187b4a. Closes #3832. 2018-02-23 19:39:19 +00:00			`* Read through the [Common Issues](Common-Issues.md).`
put troubleshooting steps in order of specificity 2016-11-06 17:43:49 +00:00
Import docs from wiki. Closes Homebrew/homebrew#33211. 2014-10-26 14:54:36 +00:00			`## Check to see if the issue has been reported`
revise troubleshooting doc 2016-11-06 18:15:58 +00:00
update: migrate everyone from linuxbrew-core to homebrew-core Co-authored-by: Mike McQuaid <mike@mikemcquaid.com> 2021-10-20 11:01:38 +01:00			`* Search the [Homebrew/homebrew-core issue tracker](https://github.com/Homebrew/homebrew-core/issues) to see if someone else has already reported the same issue.`
Update Linuxbrew references to Homebrew on Linux This is a clearer branding for us to use. Also, as part of testing this, make some fixes to Jekyll in the docs folder. Fixes #5835 2019-03-12 20:13:38 +00:00			`* If a formula that has failed to build is part of a non-core tap or a cask is part of [homebrew/cask](https://github.com/Homebrew/homebrew-cask/issues) check those issue trackers instead.`
docs: add discussion forums to troubleshooting 2020-09-08 23:32:06 +10:00			`* Search the [Homebrew discussion forum](https://github.com/homebrew/discussions/discussions) or [Discourse](https://discourse.brew.sh/) to see if any discussions have started about the issue.`
revise troubleshooting doc 2016-11-06 18:15:58 +00:00
Import docs from wiki. Closes Homebrew/homebrew#33211. 2014-10-26 14:54:36 +00:00			`## Create an issue`
revise troubleshooting doc 2016-11-06 18:15:58 +00:00
			`If your problem hasn't been solved or reported, then create an issue:`

Various documentation edits Mostly edits to formatting, grammar, wording for consistency & readability. 2018-10-05 17:23:22 -04:00			`1. Upload debugging information to a [Gist](https://gist.github.com):`
Update Linuxbrew references to Homebrew on Linux This is a clearer branding for us to use. Also, as part of testing this, make some fixes to Jekyll in the docs folder. Fixes #5835 2019-03-12 20:13:38 +00:00
			* If you had a formula-related problem: run `brew gist-logs <formula>` (where `<formula>` is the name of the formula).
			* If you encountered a non-formula problem: upload the output of `brew config` and `brew doctor` to a new [Gist](https://gist.github.com).

update: migrate everyone from linuxbrew-core to homebrew-core Co-authored-by: Mike McQuaid <mike@mikemcquaid.com> 2021-10-20 11:01:38 +01:00			`2. Create a new issue on the [Homebrew/homebrew-core issue tracker](https://github.com/Homebrew/homebrew-core/issues/new/choose)`
Update Linuxbrew references to Homebrew on Linux This is a clearer branding for us to use. Also, as part of testing this, make some fixes to Jekyll in the docs folder. Fixes #5835 2019-03-12 20:13:38 +00:00
			`* Give your issue a descriptive title which includes the formula name (if applicable) and the version of macOS or Linux you are using. For example, if a formula fails to build, title your issue "\<formula> failed to build on \<10.x>", where "\<formula>" is the name of the formula that failed to build, and "\<10.x>" is the version of macOS or Linux you are using.`
			* Include the URL output by `brew gist-logs <formula>` (if applicable).
			* Include links to any additional Gists you may have created (such as for the output of `brew config` and `brew doctor`).