Troubleshooting

Use this checklist before creating a Homebrew issue.

Update and diagnose

Run brew update.
Run brew update again so the first update cannot leave the failing command on an older Homebrew version.
Run brew doctor and read every warning.
Correct warnings that apply to the failing command.
Retry the original command and keep its complete output.

Do not apply destructive Git, ownership or permission changes from an old issue report without understanding which files they affect. See Common Issues for current recovery guidance.

Search existing reports

Search the tracker responsible for the failing component:

Homebrew/homebrew-core issues for formulae
Homebrew/homebrew-cask issues for casks
Homebrew/brew issues for the brew command
The tap's own tracker for a formula, cask or command from a non-Homebrew tap

Also search Homebrew Discussions for support and related reports. The Discourse archive is read-only historical material and will contain outdated instructions.

Collect diagnostic information

For a formula installation or build failure, upload its logs:

brew gist-logs FORMULA

For other failures, collect:

brew config
brew doctor

Remove credentials, private repository URLs and other secrets before publishing terminal output. Do not omit warnings merely because they appear unrelated.

Create an issue

If the problem is neither resolved nor already reported, use the issue template in the appropriate repository:

Include the command, complete error, relevant brew config and brew doctor output and the brew gist-logs URL when available. Use a descriptive title that identifies the package, failure and operating system.

See Creating a Homebrew Issue for reporting expectations.