Recently, there was an update to asdf which broke my install. I experienced this on macOS, Linux and WSL (which is basically Linux in Windows). This issue was due to asdf being rewritten in GoLang so a lot changed. For those who don't know what asdf is, you can probably just ignore this article. But, basically, it is a runtime version manager, so you can manage various versions of Python, Node, Ruby, Rust, GoLang and more. I use to use rvm for many years, but as my needs grew, I looked for other toolings and landed with asdf.

You can read about the releases notes here and upgrade guide here.

But, to sum up the major changes that I experienced and how I upgraded from < 0.16.x to 0.16.x, keep reading.

Fixing my install

On my macOS computer, I normally run brew upgrade and most often, it doesn't cause any problems. I like finding out these kinds of issues early on so that I can address them before I'm blindsided when working on something critical. So, I make it a habit to only run updates when there is a critical vulnerability patch or if I know that there is time to troubleshoot any kind of issues.

Thankfully, this was one of those routine maintenance times because I noticed that after I upgraded to asdf, my Ruby Interpreter was no longer working as expected.

The first hint that something was wrong with asdf was an error message when I launched a new terminal. Side note: Typically, I do not modify my .bashrc or .zshrc files, but instead will put all of my config in a .devrc as you see in the image below. In my .zshrc file, I'll source this dot file with source ~/.devrc.

This error message clearly pointed to an issue with asdf which began my troubleshooting. I first went to see what version of Ruby I was using by default now. To my surprise, it was using the version that ships with macOS instead of my asdf version.

So, I did some research and found the upgrade guide and release notes that I linked above. There was a lot of information in there so I'm going to give the TLDR version here.

You'll need to update your dot file (.zshrc, .bashrc, or .devrc) and remove the original line. Luckily the error message tells you what line this happened on so it was easy enough to spot. But, you'll then want to add the following:

export ASDF_DATA_DIR="$HOME/.asdf"
export PATH="$ASDF_DATA_DIR/shims:$PATH"

Once you save the file and close it. It's best to start up a new terminal. You could always run source .devrc but in some situations, I do not find that to always work. So, let's just assume that you launch a new terminal and then try to get the Ruby version again.

Luckily, there's no errors this time and the Ruby version returns the correct one that I installed via asdf.

Other TL;DR; on the new changes with asdf

There are some other things that have changed.

asdf list-all

has now become

asdf list all

So, the - 's have been removed from the commands.

Also, I use to be able to set my global versions with a command like

asdf global ruby 3.4.1

but this has also changed to

asdf set --home ruby 3.4.1

And that's pretty much it

Luckily this change with asdf didn't cause an all day problem. It was pretty quick to resolve, but it did take some investigative work. It's not often that we see a patch version have such a significant impact, but they definitely can as we have so clearly seen in this update.

I should also say that I'm incredibly grateful to the development community and those who have put time and effort into these version managers. They make life so much easier. The point of this post isn't to bash on their works at all, but rather to share an experience that I had.