Troubleshooting Brew Doctor Errors and Resolving ‘Invalid Bottle Tag Symbol’ Issue

4 min readJun 27, 2023

Troubleshooting Brew Doctor Errors

Recently, while trying to install different versions of PHP using homebrew, I can across some issues which I would like to highlight here along with their solutions that worked for me.

To install PHP using homebrew, you need to have:

1. Prerequisites

You’ll need both Xcode Command Line Tools and Homebrew installed.

1.1 XCode Command Line Tools
To check if this is installed

xcode-select --version

If the above command returns the:

zsh: command not found: xcode

that means you need to install the Xcode command line tools, use the following command to do so:

xcode-select --install

1.2 Homebrew
Homebrew is a package manager for macOS. It’s like apt on Ubuntu.

To check if it is already installed, run brew _— version and you should see some output like this:

$ brew --version
Homebrew 4.0.25-4-g59bc0e9
Homebrew/homebrew-core (git revision 83616b7938b; last commit 2023-03-13)

If you receive some output like this:

zsh: command not found: brew

That means we need to install Homebrew as it is not installed already. To install Homebrew, run the following command in the terminal:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Brew Doctor Errors

Run the brew doctor, to check if everything is up to date and working, if everything is good, you should see this message:

$ brew doctor
Your system is ready to brew.

but in my case, I got these issues:

Warning: Unbrewed header files were found in /usr/local/include.
If you didn't put them there on purpose they could cause problems when
building Homebrew formulae, and may need to be deleted.

Unexpected header files:
    /usr/local/include/node/ares.h
    /usr/local/include/node/ares_version.h
    /usr/local/include/node/nameser.h
    /usr/local/include/node/node.h
    /usr/local/include/node/node_buffer.h
    /usr/local/include/node/node_internals.h
    /usr/local/include/node/node_object_wrap.h
....

The above issues occur if you have installed some software/tools on your Mac without using homebrew. I had installed the “node” without using homebrew so the above issues were occurring for me.

You have two choices now:

Choose not to take any action, but keep this information in mind to avoid confusion between the source of these elements and why there may be issues with homebrew.
Eliminate those elements and instead utilize homebrew to install nodejs (and/or any other tool which is complaining).

Let’s try to implement the second option as it is the resolution of the errors that we are getting above.

Launch Finder and navigate to the top menu. Select “Go” and then choose “Go to Folder.”
Search for /user/local/include and if you find any node-related folders/terminals/files, just delete them.
After deleting the above, run brew doctor again and if the problem persists, that means the “node” is not uninstalled yet. (You can also confirm it by running “node — version” and you may see the node version installed.) And we need to uninstall the node manually and then install it (if needed) using Brew.

How to uninstall Node.js manually

This process can be quite laborious when it comes to removing Node.js, as it involves manually deleting specific files. Please proceed with caution and follow these instructions closely:

Launch Finder and navigate to the top menu. Select “Go” and then choose “Go to Folder.”
In the text box that appears, type “/usr/local/lib” (without quotation marks) and click “Go.”
Look for any files that contain the term “node” in their names and drag them to the Trash can.
Repeat the above steps for each directory listed below, and once you’ve completed this process, you’re finished.

/usr/local/bin
/opt/local/bin/
/opt/local/lib/
/usr/local/lib/dtrace/
/opt/local/include/
/usr/local/include
/usr/local/share/doc/
/usr/local/share/man/man1/
/usr/local/share/systemtap/tapset/

After following the above steps, brew doctor should now return:

$ brew doctor
Your system is ready to brew.

Resolving “Invalid Bottle Tag Symbol” Issue

Please make sure you fulfill the prerequisites mentioned above for this step as well.

While installing the legacy PHP versions (like PHP v7.2), I needed to use some taps in brew to be able to install the legacy, not supported or maintained, PHP versions by brew.

So I installed this tap named “exolnet/deprecated” using this command:

$ brew tap exolnet/homebrew-deprecated

It was installed successfully but then when I tried to install the PHP version with brew, I started getting this error:

$ brew install php@7.2
Error: php@7.1: Invalid bottle tag symbol

The reason is that the “exolnet/deprecated” tap is archived and no more supported or maintained.

So, I then uninstalled it using:

$ brew untap exolnet/homebrew-deprecated

And installed another tap named “shivammathur/php” using this command:

$ brew shivammathur/php

And then I was able to use brew for installing PHP versions without any issues.

Please keep in mind that “shivammathur/php” is a third-party tap that is not affiliated with the Homebrew organization, so they cannot vouch for anything you install from there. Please make sure you trust the contents of that tap before installing anything from it.

Last Updated: 27th June’23