bug: Misleading "no version is set for command" errors

[hannah-computer]

Describe the Bug

Our .tool-versions file is checked-in with our repo.
It was updated to bump from ruby 3.2.2 to ruby 3.2.3.
Now when I try to run it locally, I'm getting this message:

$ ruby --version                                        
No version is set for command ruby
Consider adding one of the following versions in your config file at ./.tool-versions
ruby 3.2.2

Initially I thought that was a bug in asdf, since of course a version is set for ruby, I just don't have it installed:

$ asdf list
ruby
  3.2.2

Instead of doing what the error told me and editing the shared versions file, what I actually had to do was run:

$ asdf install

Which bumped my installed version to 3.2.3 as specified, and all is good.

Steps to Reproduce

echo "ruby 3.2.2" > .tool-versions
asdf install

# some time later: simulate a pull from upstream
echo "ruby 3.2.3" > .tool-versions
ruby --version
# ^ confusing error
asdf install
ruby --version
# ^ all good.

Expected Behaviour

For the case where a .tool-versions exists, I think the error message should say something like:

$ ruby --version
The ./.tool-versions file specifies version 3.2.3 for command ruby, but you have 3.2.2 installed.
To fix this, either
- run `asdf install ruby` to install the specified version
- or change it to `ruby 3.2.2`

The error message in the case where no file exists is reasonable though:

$ ruby --version
No version is set for command ruby
Consider adding one of the following versions in your config file at ./.tool-versions
ruby 3.2.3
ruby 3.2.2

Actual Behaviour

$ ruby --version                                        
No version is set for command ruby
Consider adding one of the following versions in your config file at ./.tool-versions
ruby 3.2.2

• "no version is set" is just wrong, it is set in the file.
• doesn't print the specified version it's missing
• doesn't suggest running asdf install to resolve the issue without editing the spec -- this might be personal preference, but IMO with the spec file being hand-edited, I'd assume whatever version we find in there is intentional, so the suggestion to just install what's declared there seems generally more reasonable to me.

Environment

$ asdf info   
OS:
Darwin Hannahs-MBP.localdomain 25.2.0 Darwin Kernel Version 25.2.0: Tue Nov 18 21:09:56 PST 2025; root:xnu-12377.61.12~1/RELEASE_ARM64_T6041 arm64

SHELL:
zsh 5.9 (arm64-apple-darwin25.0)

BASH VERSION:
3.2.57(1)-release

ASDF VERSION:
0.18.0 (revision unknown)

ASDF INTERNAL VARIABLES:
ASDF_TOOL_VERSIONS_FILENAME=.tool-versions
ASDF_DATA_DIR=/Users/hannah/.asdf
ASDF_CONFIG_FILE=/Users/hannah/.asdfrc

ASDF INSTALLED PLUGINS:
ruby      https://github.com/asdf-vm/asdf-ruby.git
          b851b99d9a7006a93012f49abb1d5e5f9882e750

asdf plugins affected (if relevant)

Plugin-agnostic I believe

[mcandre]

Yeah, I've been getting this nasty bug, intermittently for the past year or two of using asdf.

Cannot recall the specific set of plugins effect. I've used asdf with Go, Rust, Ruby, Node.js, Java, PHP, and .NET before.

Sometimes, removing the component and reinstalling it with asdf install would work.

Sometimes, removing and reinstalling the plugin would seem to help.

Since asdf install don't work today, trying asdf install ruby 4.0.1.

[mcandre]

Good news!

I belatedly discovered a user error today. Instead of ruby 4.0.1 in my .tool-versions file, I had accidentally written 4.0.1.

asdf fails to validate the configuration file, so it took me a while to discover that on my own.