"rails: command not found" in CI

By Daniel Zoghalchali·Latchkey

The shell could not find a rails executable. On a fresh runner the rails command exists only through the bundle (or a binstub), so calling it bare before installing or without bundle exec fails.

What this error means

A step calling rails ... exits 127 with "rails: command not found". The same command works locally where rails is on PATH via a global gem or rbenv shim.

$ rails db:migrate
/bin/sh: 1: rails: command not found

Common causes

Not run through Bundler

rails is provided by the railties gem in the bundle. Without bundle exec or a binstub, the bare rails command is not on PATH.

Bundle not installed yet

The step runs before bundle install, so no gem executables exist.

Missing binstub

bin/rails was not committed or not generated, so there is no project-local launcher.

How to fix it

Invoke via Bundler or the binstub

1. Use bundle exec rails ... or commit and call bin/rails ....
2. Ensure bundle install (or ruby/setup-ruby with bundler-cache) ran first.
3. Generate binstubs: bundle binstubs railties and commit bin/rails.

bundle install
bundle exec rails db:migrate
# or: bin/rails db:migrate

How to prevent it

• Standardize on bundle exec rails or bin/rails in CI.
• Run bundle install before any rails command.
• Commit binstubs so the launcher is always present.

Frequently asked questions

Related guides

References

• Bundler documentation
• GitHub Actions documentation