Developer Headaches on macOS Catalina: Xcode, Homebrew, Gems

Dirk Avery

Follow

Oct 23, 2019 · 6 min read

If you’re a developer and you’ve upgraded to macOS Catalina Version 10.15, chances are you have or will see some errors. Below we’ll look at examples of errors and some common fixes!

Setting up your Mac for development for the first time? See my article Zero to Hero: Set Up Your Mac for Software Development.

Errors and problems

After upgrading to Catalina, I’ve run into three types of issues: Xcode, Homebrew, and Ruby/Gems-related. If you use Xcode, I recommend fixing Xcode first. Many developer tools on Macs rely on Xcode behind the scenes.

While these issues will mostly affect developers, the fixes might help others as well.

Xcode Errors

With the Catalina upgrade, my Xcode did not automatically update to 11.1. The App Store kept trying to update Xcode each night through automatic updates. On its own, it never succeeded. Once it reported it could not download Xcode:

Unable to Download App. "Xcode" could not be installed. Please try again later.

Most of the time, my Mac simply reported failure:

Unable to Install Update.

When I tried to run a tool that relies on Xcode, the Mac gave this xcrun error:

xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun.

Xcode Fixes

The type of Xcode fix you’ll need depends on the answer to one big question: do you use full Xcode? Most developers will probably have the whole enchilada. You can check by going to Finder, then Applications, and look for “Xcode.app.” If you see that, you’re using full Xcode.

Xcode Command-Line Tools (not full Xcode)

If you’re just using the Xcode command-line tools (less than 200 MB) versus full Xcode (about 16 gigabytes when extracted), you can save a lot of download time.

To fix Xcode command-line tools, also known as xcode-select, but not Xcode — it’s confusing I know — try this command:

xcode-select --install

If that doesn’t fix the issue, restart and try a reset:

xcode-select --reset

Xcode

Most developers will need all of Xcode. The best way to fix Xcode is to download and install Xcode yourself rather than relying on the App Store or automatic updates. Prepare yourself because you’re going to need nearly 30 GB of free space, an Apple Developer account, and a fast connection to download over 7 GB.

This is the process to fix/upgrade Xcode:

1. Go to the Apple Developer site and login
2. From the More Software section, click on Xcode 11.4 (or 11.5 when it comes out) and download the Xcode 11.1.xip file. You are fine to save it to the Downloads folder.
3. Once the XIP is downloaded, double click to begin extracting Xcode. Follow the prompts and accept the terms (assuming that in fact that you, of your own free will, and on the advice of counsel, do accept the terms).
4. Once extracted, drag the Xcode.app to the Applications folder (often shown under Favorites). When asked, answer that you want to replace the existing and older Xcode.

Once you complete this process, your App Store should soon stop being a politician — begging to perform a task it can’t complete.

Homebrew errors

Homebrew (“Brew”) per se did not have issues after the Catalina upgrade. However, some packages delivered through formulae and casks have not been updated for Catalina and are stuck back in Mojave (or High Sierra, eek!). Old packages will likely have issues with Catalina since a lot has changed.

For example, Catalina now uses Ruby 2.6. Any packages expecting to find Ruby 2.3 are going to have problems. Most have been updated now. However, just after Catalina came out, many formulas (i.e., formulae), like the Travis CI CLI Brew package, hadn’t been updated for Catalina and were still looking for Ruby 2.3.

$ travis
/usr/local/bin/travis: /usr/local/Cellar/travis/1.8.10/libexec/bin/travis: /System/Library/Frameworks/Ruby.framework/Versions/2.3/usr/bin/ruby: bad interpreter: No such file or directory
/usr/local/bin/travis: line 2: /usr/local/Cellar/travis/1.8.10/libexec/bin/travis: Undefined error: 0

Homebrew fixes

I’ve seen reports suggesting that problem packages can be fixed through a package reinstall. While this did not fix any specific issues that I had, the procedure ran fine and will hopefully prevent problems.

Reinstalling fixes issues such as when a package has incorrect pre-Catalina configuration or the Catalina version of a package has not yet been installed. Reinstalling should preserve user package settings unlike uninstalling and installing again. Reinstalling a package will not fix anything if there is no Catalina-specific formula.

To reinstall a single package, run this command:

$ brew reinstall tesseract

However, if you prefer to take an elephant gun to a squirrel hunt, like me — note that I’m not condoning the harming of animals — you can preemptively reinstall everything! Depending on how many formulae you have, and your connection speed, this might take a minute.

$ brew list | xargs brew reinstall

Gem errors

Even if you’re not a Ruby developer, a lot of general development tools are written in Ruby and so the Ruby-version change in Catalina might still affect you. Similar to Homebrew, any pre-Catalina Gems you have lying around will probably be boogered up now.

Like Python, macOS includes a system Ruby that cannot (i.e., should not) be messed up. Catalina includes two significant Ruby changes:

1. The system Ruby version was upgraded from 2.3 to 2.6, and
2. The /Library/Ruby directory used by macOS is no longer writable — it is not a place for installing user gems.

If you are calling the macOS system Ruby and try to install a gem under /Library on Catalina, you’ll receive this error:

You don't have write permissions for the /Library/Ruby/Gems/2.6.0 directory.

Gem fixes

There are probably many ways to fix the Catalina-related gem problems. Here I present one good solution that’s suitable to most situations.

As with Python, don’t use the system Ruby for development. Install Ruby and maintain a separate user Ruby and user gems.

Here is the procedure to setup a separate, non-system, user Ruby:

1. Take note of pre-Catalina gems to make reinstalling them easier:
   $ gem list
2. Use Homebrew to install Ruby after upgrading to Catalina — Ruby will be “keg only,” meaning it is not symlinked to /usr/local so it won’t interfere with the system Ruby but you’ll need to modify your path:
   $ brew install ruby
   If you were already using Homebrew for Ruby, reinstall Ruby:
   $ brew reinstall ruby
3. Add the user/Homebrew Ruby to your path first to avoid the system Ruby. For example, if you use Bash, modify your ~/.bash_profile with the following path:
   export RUBY_HOME=/usr/local/opt/ruby/bin
export PATH=$RUBY_HOME:$PATH
4. Add the new user gems binary directory to your path. For example, add the following to your ~/.bash_profile (note, GEM_PATH can include multiple paths where Gem will look for Gems whilst GEM_HOME is a single directory that is the default location for Gems — here I just use one directory for both):
   export GEM_PATH=/usr/local/opt/ruby/lib/ruby/gems/2.7.0
export GEM_HOME=$GEM_PATH
export PATH=$RUBY_HOME:$GEM_HOME/bin:$PATH
5. When you want to install a gem, use the --user-install option. For example, this will install the Travis CI CLI gem:
   $ gem install travis --user-install

Follow us on Twitter 🐦 and Facebook 👥 and join our Facebook Group 💬.

To join our community Slack 🗣️ and read our weekly Faun topics 🗞️, click here⬇

If this post was helpful, please click the clap 👏 button below a few times to show your support for the author! ⬇