brew/docs/Common-Issues.md

# Common Issues

This is a list of commonly encountered problems, known issues, and their solutions.

### `brew` complains about absence of "Command Line Tools"
You need to have the Xcode Command Line Utilities installed (and updated): run `xcode-select --install` in the terminal.

### Ruby: `bad interpreter: /usr/bin/ruby^M: no such file or directory`
You cloned with `git`, and your Git configuration is set to use Windows line endings. See this page: <https://help.github.com/articles/dealing-with-line-endings>

### Ruby: `bad interpreter: /usr/bin/ruby`
You don't have a `/usr/bin/ruby` or it is not executable. It's not recommended to let this persist; you'd be surprised how many `.app`s, tools and scripts expect your macOS-provided files and directories to be *unmodified* since macOS was installed.

### `brew update` complains about untracked working tree files
After running `brew update`, you receive a Git error warning about untracked files or local changes that would be overwritten by a checkout or merge, followed by a list of files inside your Homebrew installation.

This is caused by an old bug in in the `update` code that has long since been fixed. However, the nature of the bug requires that you do the following:

```sh
cd "$(brew --repository)"
git reset --hard FETCH_HEAD
```

If `brew doctor` still complains about uncommitted modifications, also run this command:

```sh
cd "$(brew --repository)/Library"
git clean -fd
```

### `launchctl` refuses to load launchd plist files
When trying to load a plist file into launchctl, you receive an error that resembles

```
Bug: launchctl.c:2325 (23930):13: (dbfd = open(g_job_overrides_db_path, [...]
launch_msg(): Socket is not connected
```

or

```
Could not open job overrides database at: /private/var/db/launchd.db/com.apple.launchd/overrides.plist: 13: Permission denied
launch_msg(): Socket is not connected
```

These are likely due to one of four issues:

1. You are using iTerm. The solution is to use Terminal.app when interacting with `launchctl`.
2. You are using a terminal multiplexer such as `tmux` or `screen`. You should interact with `launchctl` from a separate Terminal.app shell.
3. You are attempting to run `launchctl` while logged in remotely. You should enable screen sharing on the remote machine and issue the command using Terminal.app running on that machine.
4. You are `su`'ed as a different user.

### `brew upgrade` errors out
When running `brew upgrade`, you see something like this:

```
$ brew upgrade
Error: undefined method `include?' for nil:NilClass
Please report this bug:
    https://docs.brew.sh/Troubleshooting
/usr/local/Library/Homebrew/formula.rb:393:in `canonical_name'
/usr/local/Library/Homebrew/formula.rb:425:in `factory'
/usr/local/Library/Contributions/examples/brew-upgrade.rb:7
/usr/local/Library/Contributions/examples/brew-upgrade.rb:7:in `map'
/usr/local/Library/Contributions/examples/brew-upgrade.rb:7
/usr/local/bin/brew:46:in `require'
/usr/local/bin/brew:46:in `require?'
/usr/local/bin/brew:79
```

This happens because an old version of the upgrade command is hanging around for some reason. The fix:

```sh
cd "$(brew --repository)/Library/Contributions/examples"
git clean -n # if this doesn't list anything that you want to keep, then
git clean -f # this will remove untracked files
```

### Python: `easy-install.pth` cannot be linked

```
Warning: Could not link <formula>. Unlinking...
Error: The `brew link` step did not complete successfully
The formula built, but is not symlinked into /usr/local
You can try again using `brew link <formula>'

Possible conflicting files are:
/usr/local/lib/python2.7/site-packages/site.py
/usr/local/lib/python2.7/site-packages/easy-install.pth
==> Could not symlink file: /homebrew/Cellar/<formula>/<version>/lib/python2.7/site-packages/site.py
Target /usr/local/lib/python2.7/site-packages/site.py already exists. You may need to delete it.
To force the link and overwrite all other conflicting files, do:
  brew link --overwrite formula_name

To list all files that would be deleted:
  brew link --overwrite --dry-run formula_name
```

Don't follow the advice here but fix by using
`Language::Python.setup_install_args` in the formula as described in
[Python for Formula Authors](Python-for-Formula-Authors.md).

### Upgrading macOS

Upgrading macOS can cause errors like the following:

- `dyld: Library not loaded: /usr/local/opt/icu4c/lib/libicui18n.54.dylib`
- `configure: error: Cannot find libz`

Following a macOS upgrade it may be necessary to reinstall the Xcode Command Line Tools and `brew upgrade` all installed formula:

```sh
xcode-select --install
brew upgrade
```

### Other local issues

If your Homebrew installation gets messed up (and fixing the issues found by `brew doctor` doesn't solve the problem), reinstalling Homebrew may help to reset to a normal state. To easily reinstall Homebrew, use [Homebrew Bundle](https://github.com/Homebrew/homebrew-bundle) to automatically restore your installed formulae and casks. To do so, run `brew bundle dump`, [uninstall](https://docs.brew.sh/FAQ#how-do-i-uninstall-homebrew), [reinstall](https://docs.brew.sh/Installation) and run `brew bundle install`.
Import docs from wiki. Closes Homebrew/homebrew#33211. 2014-10-26 14:54:36 +00:00			`# Common Issues`
docs: fix titles on docs.brew.sh 2017-01-04 16:16:00 -06:00
Import docs from wiki. Closes Homebrew/homebrew#33211. 2014-10-26 14:54:36 +00:00			`This is a list of commonly encountered problems, known issues, and their solutions.`

			### `brew` complains about absence of "Command Line Tools"
			You need to have the Xcode Command Line Utilities installed (and updated): run `xcode-select --install` in the terminal.

docs: grammar edits, sentence-case secondary headings Also changes some heading levels so only one primary heading appears per page. 2017-03-18 17:45:12 -04:00			### Ruby: `bad interpreter: /usr/bin/ruby^M: no such file or directory`
			You cloned with `git`, and your Git configuration is set to use Windows line endings. See this page: <https://help.github.com/articles/dealing-with-line-endings>
Import docs from wiki. Closes Homebrew/homebrew#33211. 2014-10-26 14:54:36 +00:00
docs: grammar edits, sentence-case secondary headings Also changes some heading levels so only one primary heading appears per page. 2017-03-18 17:45:12 -04:00			### Ruby: `bad interpreter: /usr/bin/ruby`
			You don't have a `/usr/bin/ruby` or it is not executable. It's not recommended to let this persist; you'd be surprised how many `.app`s, tools and scripts expect your macOS-provided files and directories to be unmodified since macOS was installed.
Import docs from wiki. Closes Homebrew/homebrew#33211. 2014-10-26 14:54:36 +00:00
			### `brew update` complains about untracked working tree files
docs: grammar edits, sentence-case secondary headings Also changes some heading levels so only one primary heading appears per page. 2017-03-18 17:45:12 -04:00			After running `brew update`, you receive a Git error warning about untracked files or local changes that would be overwritten by a checkout or merge, followed by a list of files inside your Homebrew installation.
Import docs from wiki. Closes Homebrew/homebrew#33211. 2014-10-26 14:54:36 +00:00
			This is caused by an old bug in in the `update` code that has long since been fixed. However, the nature of the bug requires that you do the following:

docs: code example reformatting Add labeled fences to most code blocks, monospace terms where appropriate, omit "$" when referring to variables 2017-03-25 22:53:33 -04:00			```sh
style: fix inconsistent code style for shell scripts 2021-09-13 20:32:20 +08:00			`cd "$(brew --repository)"`
Import docs from wiki. Closes Homebrew/homebrew#33211. 2014-10-26 14:54:36 +00:00			`git reset --hard FETCH_HEAD`
			```
docs: code example reformatting Add labeled fences to most code blocks, monospace terms where appropriate, omit "$" when referring to variables 2017-03-25 22:53:33 -04:00
Import docs from wiki. Closes Homebrew/homebrew#33211. 2014-10-26 14:54:36 +00:00			If `brew doctor` still complains about uncommitted modifications, also run this command:
docs: code example reformatting Add labeled fences to most code blocks, monospace terms where appropriate, omit "$" when referring to variables 2017-03-25 22:53:33 -04:00
			```sh
style: fix inconsistent code style for shell scripts 2021-09-13 20:32:20 +08:00			`cd "$(brew --repository)/Library"`
Import docs from wiki. Closes Homebrew/homebrew#33211. 2014-10-26 14:54:36 +00:00			`git clean -fd`
			```

			### `launchctl` refuses to load launchd plist files
			`When trying to load a plist file into launchctl, you receive an error that resembles`

			```
			`Bug: launchctl.c:2325 (23930):13: (dbfd = open(g_job_overrides_db_path, [...]`
			`launch_msg(): Socket is not connected`
			```
docs: code example reformatting Add labeled fences to most code blocks, monospace terms where appropriate, omit "$" when referring to variables 2017-03-25 22:53:33 -04:00
Import docs from wiki. Closes Homebrew/homebrew#33211. 2014-10-26 14:54:36 +00:00			`or`

docs: code example reformatting Add labeled fences to most code blocks, monospace terms where appropriate, omit "$" when referring to variables 2017-03-25 22:53:33 -04:00			```
Import docs from wiki. Closes Homebrew/homebrew#33211. 2014-10-26 14:54:36 +00:00			`Could not open job overrides database at: /private/var/db/launchd.db/com.apple.launchd/overrides.plist: 13: Permission denied`
			`launch_msg(): Socket is not connected`
			```

Documentation Changes More proposed documentation updates. Acceptable Formulae: * Adds Perl to the list of stuff we offer Dupes of in the Core. * Notes that OS X’s OpenSSL is usually horribly outdated. * Removes the incorrect space between font and forge. Common Issues: * We said three issues, we listed four. Oops. External Commands: * The cache is usually at /Library rather than ~/Library, and the rest of the documentation says /Library, so this makes the referencing consistent. FAQ: * Adds a tiny section on pinning formulae. Interesting-Taps-And-Branches: * Notes gaming-emulation software belongs in Homebrew/Games as well. * nolith/Embedded hasn’t been touched for 28 months. I’ve cut it. * anarchivist/forensics hasn’t been touched for 35 months. I’ve cut it. * codebutler’s GTK+ experiment seems to have been terminated after one commit. I’ve cut it. * paxam/linux hasn’t been touched for 34 months. I’ve cut it. * rmyers/homebrew hasn’t been touched in 42 months. I’ve cut it. * nddrylliog/winbrew has moved, I’ve changed the URL to the new one. Winbrew.md: * Removed. It’s referenced in the prior file, and doesn’t really need its own. Closes Homebrew/homebrew#34599. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com> 2014-12-02 03:25:31 +00:00			`These are likely due to one of four issues:`
Import docs from wiki. Closes Homebrew/homebrew#33211. 2014-10-26 14:54:36 +00:00
			1. You are using iTerm. The solution is to use Terminal.app when interacting with `launchctl`.
			2. You are using a terminal multiplexer such as `tmux` or `screen`. You should interact with `launchctl` from a separate Terminal.app shell.
Various documentation edits Mostly edits to formatting, grammar, wording for consistency & readability. 2018-10-05 17:23:22 -04:00			3. You are attempting to run `launchctl` while logged in remotely. You should enable screen sharing on the remote machine and issue the command using Terminal.app running on that machine.
docs: code example reformatting Add labeled fences to most code blocks, monospace terms where appropriate, omit "$" when referring to variables 2017-03-25 22:53:33 -04:00			4. You are `su`'ed as a different user.
Import docs from wiki. Closes Homebrew/homebrew#33211. 2014-10-26 14:54:36 +00:00
			### `brew upgrade` errors out
			When running `brew upgrade`, you see something like this:
docs: code example reformatting Add labeled fences to most code blocks, monospace terms where appropriate, omit "$" when referring to variables 2017-03-25 22:53:33 -04:00
			```
Import docs from wiki. Closes Homebrew/homebrew#33211. 2014-10-26 14:54:36 +00:00			`$ brew upgrade`
			Error: undefined method `include?' for nil:NilClass
			`Please report this bug:`
docs.brew.sh updates - Remove no longer needed `acme-challenge` file - Set title, description, social image, logo, etc. for SEO - Use extensionless permalinks (old links still work) - Cleanup `_config.yml` - Import latest `_layouts/base` from https://brew.sh 2018-02-22 18:47:29 +00:00			`https://docs.brew.sh/Troubleshooting`
Import docs from wiki. Closes Homebrew/homebrew#33211. 2014-10-26 14:54:36 +00:00			/usr/local/Library/Homebrew/formula.rb:393:in `canonical_name'
			/usr/local/Library/Homebrew/formula.rb:425:in `factory'
			`/usr/local/Library/Contributions/examples/brew-upgrade.rb:7`
			/usr/local/Library/Contributions/examples/brew-upgrade.rb:7:in `map'
			`/usr/local/Library/Contributions/examples/brew-upgrade.rb:7`
			/usr/local/bin/brew:46:in `require'
			/usr/local/bin/brew:46:in `require?'
			`/usr/local/bin/brew:79`
			```

			`This happens because an old version of the upgrade command is hanging around for some reason. The fix:`

docs: code example reformatting Add labeled fences to most code blocks, monospace terms where appropriate, omit "$" when referring to variables 2017-03-25 22:53:33 -04:00			```sh
style: fix inconsistent code style for shell scripts 2021-09-13 20:32:20 +08:00			`cd "$(brew --repository)/Library/Contributions/examples"`
docs: code example reformatting Add labeled fences to most code blocks, monospace terms where appropriate, omit "$" when referring to variables 2017-03-25 22:53:33 -04:00			`git clean -n # if this doesn't list anything that you want to keep, then`
			`git clean -f # this will remove untracked files`
Import docs from wiki. Closes Homebrew/homebrew#33211. 2014-10-26 14:54:36 +00:00			```

Various documentation edits Mostly edits to formatting, grammar, wording for consistency & readability. 2018-10-05 17:23:22 -04:00			### Python: `easy-install.pth` cannot be linked
docs: code example reformatting Add labeled fences to most code blocks, monospace terms where appropriate, omit "$" when referring to variables 2017-03-25 22:53:33 -04:00
Import docs from wiki. Closes Homebrew/homebrew#33211. 2014-10-26 14:54:36 +00:00			```
docs: code example reformatting Add labeled fences to most code blocks, monospace terms where appropriate, omit "$" when referring to variables 2017-03-25 22:53:33 -04:00			`Warning: Could not link <formula>. Unlinking...`
Import docs from wiki. Closes Homebrew/homebrew#33211. 2014-10-26 14:54:36 +00:00			Error: The `brew link` step did not complete successfully
			`The formula built, but is not symlinked into /usr/local`
docs: code example reformatting Add labeled fences to most code blocks, monospace terms where appropriate, omit "$" when referring to variables 2017-03-25 22:53:33 -04:00			You can try again using `brew link <formula>'
Import docs from wiki. Closes Homebrew/homebrew#33211. 2014-10-26 14:54:36 +00:00
			`Possible conflicting files are:`
			`/usr/local/lib/python2.7/site-packages/site.py`
			`/usr/local/lib/python2.7/site-packages/easy-install.pth`
docs: code example reformatting Add labeled fences to most code blocks, monospace terms where appropriate, omit "$" when referring to variables 2017-03-25 22:53:33 -04:00			`==> Could not symlink file: /homebrew/Cellar/<formula>/<version>/lib/python2.7/site-packages/site.py`
Import docs from wiki. Closes Homebrew/homebrew#33211. 2014-10-26 14:54:36 +00:00			`Target /usr/local/lib/python2.7/site-packages/site.py already exists. You may need to delete it.`
			`To force the link and overwrite all other conflicting files, do:`
			`brew link --overwrite formula_name`

			`To list all files that would be deleted:`
			`brew link --overwrite --dry-run formula_name`
			```

Doc maintenance Fixes Homebrew/homebrew#37698. 2015-03-13 20:48:44 -07:00			`Don't follow the advice here but fix by using`
			`Language::Python.setup_install_args` in the formula as described in
Revert "docs: use short links." This reverts commit e63a2ee8de12f0f938f6a95cdb9763dbe0187b4a. Closes #3832. 2018-02-23 19:39:19 +00:00			`[Python for Formula Authors](Python-for-Formula-Authors.md).`
Common-Issues: add section for upgrading OS X. Closes Homebrew/homebrew#47008. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com> 2015-12-14 12:38:26 -05:00
Use new "macOS" naming where appropriate. Not quite a mass replacement as I've used OS X and Mac OS X where describing specific older versions and added compatibility methods for things in the DSL. 2016-09-18 19:57:19 +01:00			`### Upgrading macOS`
Common-Issues: add section for upgrading OS X. Closes Homebrew/homebrew#47008. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com> 2015-12-14 12:38:26 -05:00
Use new "macOS" naming where appropriate. Not quite a mass replacement as I've used OS X and Mac OS X where describing specific older versions and added compatibility methods for things in the DSL. 2016-09-18 19:57:19 +01:00			`Upgrading macOS can cause errors like the following:`
Common-Issues: add section for upgrading OS X. Closes Homebrew/homebrew#47008. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com> 2015-12-14 12:38:26 -05:00
			- `dyld: Library not loaded: /usr/local/opt/icu4c/lib/libicui18n.54.dylib`
			- `configure: error: Cannot find libz`

docs: grammar edits, sentence-case secondary headings Also changes some heading levels so only one primary heading appears per page. 2017-03-18 17:45:12 -04:00			Following a macOS upgrade it may be necessary to reinstall the Xcode Command Line Tools and `brew upgrade` all installed formula:
Common-Issues: add section for upgrading OS X. Closes Homebrew/homebrew#47008. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com> 2015-12-14 12:38:26 -05:00
docs: code example reformatting Add labeled fences to most code blocks, monospace terms where appropriate, omit "$" when referring to variables 2017-03-25 22:53:33 -04:00			```sh
Common-Issues: add section for upgrading OS X. Closes Homebrew/homebrew#47008. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com> 2015-12-14 12:38:26 -05:00			`xcode-select --install`
			`brew upgrade`
			```
reinstallation instructions for build failures 2021-02-13 14:37:54 -05:00
Update docs/Common-Issues.md I think this is a substantial improvement and does what I hoped, helps folks help themselves if--say--they just want to get emacs working; next time they'll have the technique in their pocket too. Co-authored-by: Rylan Polster <rslpolster@gmail.com> 2021-04-01 15:51:00 -04:00			`### Other local issues`
reinstallation instructions for build failures 2021-02-13 14:37:54 -05:00
docs/Common-Issues: remove Oxford comma. Not sure why CI didn't catch this the first time. 2021-05-05 10:08:21 +01:00			If your Homebrew installation gets messed up (and fixing the issues found by `brew doctor` doesn't solve the problem), reinstalling Homebrew may help to reset to a normal state. To easily reinstall Homebrew, use [Homebrew Bundle](https://github.com/Homebrew/homebrew-bundle) to automatically restore your installed formulae and casks. To do so, run `brew bundle dump`, [uninstall](https://docs.brew.sh/FAQ#how-do-i-uninstall-homebrew), [reinstall](https://docs.brew.sh/Installation) and run `brew bundle install`.