rbenv "version `X' is not installed" in CI

rbenv was asked for a Ruby version that it does not have installed. The .ruby-version file (or RBENV_VERSION) names a version that was never built on this runner.

What this error means

Any ruby/gem/bundle command fails immediately with "rbenv: version 'X' is not installed", naming the file that set it. rbenv knows which version you want but has no build of it on disk.

rbenv: version `3.3.0' is not installed (set by /home/runner/work/app/.ruby-version)

The following versions are installed:
  3.2.2

Common causes

The requested Ruby was never built

A fresh runner only has the versions baked into the image. If .ruby-version names a version not installed, rbenv has nothing to select.

ruby-build plugin missing or outdated

rbenv install relies on the ruby-build plugin and its version definitions. An outdated plugin may not know a newly released Ruby.

How to fix it

Install the requested Ruby

rbenv install 3.3.0
rbenv rehash
ruby --version

Update ruby-build if the version is unknown

Refresh the build definitions so rbenv recognizes recent Ruby releases.

git -C "$(rbenv root)/plugins/ruby-build" pull
rbenv install --list | grep 3.3

How to prevent it

• Use setup-ruby (or a base image) that already provides the pinned Ruby.
• Cache the rbenv versions directory keyed on .ruby-version.
• Keep ruby-build current so new Ruby releases are installable.

Related guides