Homebrew Troubleshooting Guide

A step‑by‑step diagnostic guide for fixing common Homebrew warnings on macOS, covering permissions, network, cache, conflicts, and version checks.

Recognizable Condition

When you run brew doctor you see warnings such as:

Warning: /usr/local/bin is not writable
Error: Failed to connect to GitHub during brew update or brew install <formula>

These symptoms indicate that Homebrew cannot perform its normal operations.

Cause/Diagnostic Table

Symptom	Likely Cause
/usr/local not writable	Permission issue – /usr/local not owned by your user
Network errors	Unable to reach raw.githubusercontent.com or api.github.com
Strange cache size	Corrupt or stale files in ~/Library/Caches/Homebrew
Other package managers present	Conflicting software (MacPorts, Fink) altering PATH
Old Homebrew version	Running an outdated brew that lacks recent fixes

Ordered Checks

Run brew doctor and note any warnings. Execute this in a normal terminal; no special permissions are required.
Verify ownership of /usr/local:
```
ls -ld /usr/local
```
Look for your username in the owner field (e.g., drwxr-xr-x youruser staff ... /usr/local). If the owner is root or another user, you have a permission issue.
Test network reachability to GitHub’s raw content:
```
curl -I https://raw.githubusercontent.com/Homebrew/homebrew-core/master/README.md
```
Expect a response header containing HTTP/2 200. Anything else (timeout, 403, 502) suggests a network problem.
Inspect the Homebrew cache for abnormal files:
```
ls -la ~/Library/Caches/Homebrew
```
Look for zero‑byte files or unusually large files (> 100 MB) that may indicate corruption.
Check for competing package managers:
```
which port
which fink
```
If either returns a path, another manager is installed and may interfere with Homebrew’s /usr/local layout.
Confirm the current Homebrew version:
```
brew --version
```
Compare the output to the latest release noted on brew.sh. A significantly older version may need updating.

Fixes Tied to Findings

Permission Issue

If /usr/local is not owned by your user, change ownership:

sudo chown -R $(whoami) /usr/local

Where to run: Any terminal window; you need administrative privileges for sudo. Risk: Using sudo with Homebrew commands afterward can re‑introduce permission conflicts, so avoid sudo brew * after this step. Rollback: To restore the original state (typically owned by root:wheel), run:

sudo chown -R root:wheel /usr/local

Network Failure

If the curl test fails:

Ensure you are not behind a restrictive VPN or proxy; disable them temporarily.
Flush the DNS cache:

dscacheutil -flushcache
sudo killall -HUP mDNSResponder

Retry the curl command; if it succeeds, proceed with brew update.

Corrupt Cache

If you see suspicious files in the cache:

brew cleanup
rm -rf ~/Library/Caches/Homebrew/*

Where to run: Normal user terminal; no sudo needed. Risk: Deleting the cache forces Homebrew to re‑download bottles and source tarballs on the next operation, which may increase bandwidth usage temporarily.

Conflicting Manager

If which port or which fink returns a path:

Temporarily adjust your PATH to prioritize Homebrew:

export PATH="/usr/local/bin:/usr/local/sbin:$PATH"

Or disable the other manager’s launch agents (e.g., unload MacPorts daemon) while using Homebrew.

Outdated Homebrew

If brew --version shows an old release:

brew update
brew upgrade

Where to run: Normal terminal; no sudo. Risk: Upgrading may upgrade formulae that have breaking changes; review the upgrade output if you rely on specific versions.

Escalation Criteria

Escalate to the Homebrew issue tracker when:

brew doctor warnings persist after applying the relevant fix.
Repeated brew install failures produce core dumps or segmentation faults.
Network tests fail despite normal internet connectivity (e.g., other HTTPS sites load).

When filing a bug, include the output of brew doctor --verbose, your macOS version, and the output of brew --config.

Verification

After each fix, run:

brew doctor

Expect output that ends with Your system is ready to brew. or only informational hints.

Test a known formula installation:

brew install wget wget --version

Confirm the binary runs without error.

Finally, verify that brew update fetches the latest changes by checking the repository’s last commit:

cd $(brew --repo) && git log -1 --format=%ai

The timestamp should be recent (within the last few hours if you have internet).

Limitations

This guide covers the most frequent symptoms seen on a typical macOS installation with Homebrew in /usr/local. It does not address:

Issues arising from custom HOMEBREW_PREFIX locations.
Problems caused by third‑party patches to Homebrew’s Ruby code.
Hardware‑specific failures (e.g., disk I/O errors).

If you use a non‑default prefix, replace /usr/local with your brew --prefix in the commands above.

Diagnosing and Fixing Common Homebrew Issues on macOS