The Homebrew bug that looked like a zsh bug... but turned out to be an iTerm bug.

This bug was difficult for me to diagnose.

The first sign of trouble was that the `npm` command wasn't found. I use homebrew to manage my local node installation, and so ran brew doctor. Much to my surprise, it reported:

Warning: Homebrew's bin was not found in your PATH.
Consider setting the PATH for example like so
    echo export PATH='/usr/local/bin:$PATH' >> ~/.bash_profile

This despite the fact that `echo $PATH` clearly reported that it was set. I double-checked ~/.zshrc to make sure the path export looked right, and it did.

I eventually hopped on IRC#machomebrew channel, and a friendly person suggested I write a simple script to verify that sub-processes were receiving the PATH variable correctly. I did that, and this was my first indication that it was not a homebrew bug! I suspected that it was zsh, or oh-my-zsh, and radically simplified my login files, but the problem was still there.

About to post onto IRC#zsh when it hit me: what if my terminal is doing something funny? So I started up plain vanilla Terminal and executed the same script. It worked! This meant that it was, in fact, iTerm2's fault.

And indeed, that is the determination from this rather lengthy bug discussion.

There was both a brilliant work-around in that thread by a user github/pilif:

/usr/bin/login -f 

but the iTerm maintainers were on it, and fixed it. For some reason I did not get that update of iTerm (probably because I cancelled out of an update in my haste). The best solution was to simply update iTerm2 to the latest version, which fixes this problem.

Why write about this bug? Because it highlights the surprising ways that tools interact, and how sometimes appearances can be deceiving. It's also a reminder of how delicate software systems are, and how easily they can interact with each other in unexpected, and unwanted ways. Patience and perseverance, though, can usually result in a resolution.

I also want to say that, without exception, these are all wonderful tools, including iTerm2, who's consistent strengths definitely outweigh it's (momentarily frustrating) weakness.