asdf-vm / asdf-vm/asdf

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

Open
#2,232 2 comments 11 reactions 0 assignees View on GitHub
bug
Dominant language
Go
Stars
25.6k
Forks
941
Avg merge
9h 24m
Merged PRs (30d)
3

Description

### 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

```bash
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

```shell
$ 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

Contributor guide

Open the contributing guide

Research direction

Start by running the shell reproduction with successive .tool-versions values, then trace the ruby --version and asdf install entry points that produce the error. Done means the configured-but-uninstalled version is distinguished from no configured version, and the message gives the relevant version and a path to resolve it.

Written by the indexing model from the issue text.

Assessment

Tech stack
go, ruby, shell
Domain
cli, tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.