Rails "rails: command not found" / use bundle exec rails in CI

By Kaveh Alemi·Latchkey

The shell could not find a rails executable on PATH. In CI the Rails gem lives in the bundle, not on the global PATH, so you must invoke it through bin/rails or bundle exec rails.

What this error means

A step calling rails db:create (or similar) fails with "rails: command not found" and exit code 127.

/home/runner/work/_temp/script.sh: line 1: rails: command not found
Error: Process completed with exit code 127.

Common causes

The rails binstub is not on PATH

The bundled rails gem provides no global executable; only the project binstub bin/rails or bundle exec reaches it.

bundle install ran with a path or deployment layout

When gems install under vendor/bundle, bare rails is not on PATH; the bundle must resolve the binary.

How to fix it

Call rails through the bundle

Use the project binstub or bundle exec so the exact bundled Rails version runs.

- run: bin/rails db:prepare
  env:
    RAILS_ENV: test

Or invoke via bundle exec

When binstubs are absent, bundle exec rails resolves the gem from the lockfile.

bundle exec rails db:prepare

How to prevent it

• Always use bin/rails or bundle exec rails in CI, never bare rails.
• Commit binstubs (bin/rails) so they are available after checkout.
• Set up Ruby and run bundle install before any rails task.

Frequently asked questions

Related guides

References

• Bundler documentation
• GitHub Actions documentation