GitHub Actions ruby/setup-ruby "cannot find Ruby version"

ruby/setup-ruby installs prebuilt Ruby binaries that exist only for specific OS images. A version with no prebuilt binary for the runner, or an unreadable .ruby-version, fails before install.

What this error means

A ruby/setup-ruby step fails saying the Ruby version is unknown or has no prebuilt binary for the current runner image.

github-actions

Error: Unknown Ruby version: 3.4.99
      available versions for ubuntu-22.04: 3.4.1, 3.3.6, 3.2.6

Common causes

No prebuilt binary for the runner image

ruby/setup-ruby ships binaries per OS image; a version absent for that image (or for the OS at all) cannot be installed.

Bad or missing .ruby-version

With ruby-version: .ruby-version, a typo or missing file produces an unparseable version.

How to fix it

Request a supported version

Set ruby-version to a value listed for your runner image (the error lists available ones).
Validate the .ruby-version file contents if you read from it.
Pin the OS image so the available version set is stable.

.github/workflows/ci.yml

- uses: ruby/setup-ruby@v1
  with:
    ruby-version: '3.3'

How to prevent it

Pin the runner OS image so the prebuilt-binary set does not shift.
Keep .ruby-version aligned with what the action supports.
Latchkey managed runners auto-retry the Ruby binary download on transient failures.