erlef/setup-beam "no version found matching" in CI

setup-beam looked up the exact Elixir/OTP version you asked for in its build index and found no match for the runner OS. The action fails before Elixir is installed.

What this error means

The setup-beam step fails with "Error: no version found matching X" for an elixir-version or otp-version that is misspelled, unreleased, or missing a prebuilt for this Ubuntu image.

Error: no version found matching 1.17 (Elixir)
Consider adding a version in the format 1.17.x, or use 'latest'.

Common causes

Partial or nonexistent version string

setup-beam needs a concrete version (for example 1.17.2) or a supported range. A bare "1.17" or a version that was never released will not match.

The Elixir/OTP pair has no prebuilt for the runner

Elixir builds are compiled against a specific OTP major on a specific Ubuntu. A combination without a published artifact for that image yields no match.

How to fix it

Pin a real, compatible Elixir/OTP pair

1. Pick a released Elixir version and the OTP major it was built against.
2. Use full versions, or a range with a version-type where needed.
3. Re-run so setup-beam finds a prebuilt for the runner image.

- uses: erlef/setup-beam@v1
  with:
    otp-version: '27.0'
    elixir-version: '1.17.2'

Read from .tool-versions for one source of truth

Let setup-beam read the versions your team already uses locally so CI and dev stay aligned.

- uses: erlef/setup-beam@v1
  with:
    version-file: .tool-versions
    version-type: strict

How to prevent it

• Pin full, released Elixir and OTP versions in the workflow.
• Keep the Elixir version paired with an OTP major it supports.
• Share versions via .tool-versions so dev and CI match.

Related guides