rbenv "version X is not installed" in CI

rbenv reads the Ruby version your project pins (from .ruby-version or rbenv local) and tries to activate it. When that exact version is not installed under rbenv on the runner, rbenv refuses to fall back and reports the version as not installed.

What this error means

A command run through rbenv fails with "rbenv: version 3.3.1 is not installed (set by /app/.ruby-version)". Listing rbenv versions does not show the pinned version.

rbenv: version `3.3.1' is not installed (set by /app/.ruby-version)
Run `rbenv install 3.3.1' to install it.

Common causes

The pinned Ruby is not installed on the runner

The CI image ships different Ruby versions than your .ruby-version names, and nobody installed the pinned one before using rbenv.

ruby-build is missing the version definition

rbenv install cannot build the version because the ruby-build plugin is outdated and lacks that version’s definition.

How to fix it

Install the pinned Ruby (or use setup-ruby)

Install the exact version, or let setup-ruby provision it from .ruby-version.

# explicit rbenv
rbenv install 3.3.1
rbenv local 3.3.1

# or, in GitHub Actions
# - uses: ruby/setup-ruby@v1
#   with: { ruby-version: .ruby-version }

Update ruby-build if the version is unknown

Refresh the plugin so rbenv install recognizes the version definition.

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

How to prevent it

• Provision Ruby from .ruby-version with setup-ruby rather than relying on preinstalled versions.
• Keep ruby-build current so new patch versions are installable.
• Pin a Ruby version your runner image actually provides.

Related guides