Skip to content
Latchkey

rbenv "ruby-build: definition not found" in CI

rbenv install asked ruby-build to build a Ruby version it has no definition for. The ruby-build plugin ships a fixed list of buildable versions, and the requested release is newer than the installed plugin knows about.

What this error means

rbenv install <version> fails with "ruby-build: definition not found", listing where to look for available definitions. The version is valid and released; the plugin is simply out of date.

rbenv output
ruby-build: definition not found: 3.3.0

See all available versions with `rbenv install --list`.
...
If the version you need is missing, try upgrading ruby-build.

Common causes

Outdated ruby-build plugin

ruby-build only builds versions in its bundled definitions. A plugin predating the requested Ruby release has no definition for it.

Typo or non-existent version string

A misspelled version (or a not-yet-released one) has no definition, so ruby-build reports it as not found.

How to fix it

Update ruby-build’s definitions

Pull the latest ruby-build so it recognizes recent Ruby releases.

Terminal
git -C "$(rbenv root)/plugins/ruby-build" pull
# or via Homebrew
brew upgrade ruby-build
rbenv install --list | grep 3.3

Verify the exact version string

List available definitions and pick the precise name.

Terminal
rbenv install --list
rbenv install 3.3.0

How to prevent it

  • Keep ruby-build current in CI before installing a new Ruby.
  • Use a base image or setup-ruby that already provides the pinned Ruby.
  • Match .ruby-version to a release ruby-build can build.

Related guides

Tired of flaky CI? Latchkey auto-heals failed jobs and retries them for you. Start free →