Developer Headaches on macOS Catalina: Xcode, Homebrew, Gems

Dirk Avery
Oct 23, 2019 · 5 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!

A frustrated woman sits in front of a Macbook
A frustrated woman sits in front of a Macbook
(Photo credit: energepic)

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.

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

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.1 (or 11.2 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. For example, the Travis CI CLI Brew package hasn’t been updated for Catalina and is 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 system Ruby gems directory 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 in 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:
    export GEM_PATH=~/.gem/ruby/2.6.0
    export PATH=$GEM_PATH/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⬇

Faun

The Must-Read Publication for Aspiring Developers & DevOps Enthusiasts. Medium’s largest DevOps publication.

Dirk Avery

Written by

Cloud developer, AI buff, patent attorney, fan of cronuts. AWS Certified Solutions Architect — Professional. Go, Python, Bash. https://www.plus3it.com

Faun

Faun

The Must-Read Publication for Aspiring Developers & DevOps Enthusiasts. Medium’s largest DevOps publication.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade