From 2e3bc0b4a30bb6f29f033f5b0c53bf52d9897c19 Mon Sep 17 00:00:00 2001 From: EricFromCanada Date: Tue, 16 Nov 2021 12:47:29 -0500 Subject: [PATCH] Update Common-Issues.md --- docs/Common-Issues.md | 85 ++++++++++++++++++++----------------------- 1 file changed, 39 insertions(+), 46 deletions(-) diff --git a/docs/Common-Issues.md b/docs/Common-Issues.md index 27de877f9..3b7f14e8f 100644 --- a/docs/Common-Issues.md +++ b/docs/Common-Issues.md @@ -2,13 +2,15 @@ This is a list of commonly encountered problems, known issues, and their solutions. +## Running `brew` + ### `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: +You cloned with `git`, and your Git configuration is set to use Windows line endings. See this page on [configuring Git to handle line endings](https://docs.github.com/en/get-started/getting-started-with-git/configuring-git-to-handle-line-endings). ### Ruby: `bad interpreter: /usr/bin/ruby` @@ -34,45 +36,38 @@ 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 +When trying to load a plist file with `launchctl`, you receive an error that resembles either: -``` -Bug: launchctl.c:2325 (23930):13: (dbfd = open(g_job_overrides_db_path, [...] -launch_msg(): Socket is not connected -``` + Bug: launchctl.c:2325 (23930):13: (dbfd = open(g_job_overrides_db_path, [...] + launch_msg(): Socket is not connected -or +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 -``` + 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. +1. You are using a terminal multiplexer such as `tmux` or `screen`. You should interact with `launchctl` from a separate Terminal.app shell. +1. 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. +1. 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 -``` + 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: @@ -84,42 +79,40 @@ git clean -f # this will remove untracked files ### Python: `easy-install.pth` cannot be linked -``` -Warning: Could not link . 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 ' + Warning: Could not link . 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 ' -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///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 + 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///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 -``` + 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 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: +Following a macOS upgrade it may be necessary to reinstall the Xcode Command Line Tools and then `brew upgrade` all installed formulae: ```sh xcode-select --install brew upgrade ``` -### Other local issues +## 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`.