"rspec: command not found" in CI

By Daniel Zoghalchali·Latchkey

The rspec executable comes from the rspec-core gem in the bundle. A bare rspec call on a fresh runner has nothing on PATH to run.

What this error means

The test step exits 127 with "rspec: command not found". It works locally because rspec resolves through rbenv/global gems or an existing binstub.

$ rspec
/bin/sh: 1: rspec: command not found

Common causes

Not run through Bundler

rspec is only available via the bundle. Without bundle exec or bin/rspec, the command is not on PATH.

rspec not in the bundle

The rspec-rails or rspec gem is missing or in a group not installed in CI (e.g. a test group skipped by a without setting).

Bundle not installed

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

How to fix it

Run rspec through the bundle

1. Call bundle exec rspec or bin/rspec.
2. Confirm rspec-rails is in the :test group and that group is installed.
3. Ensure bundle install ran before the test step.

bundle install
bundle exec rspec
# or: bin/rspec

How to prevent it

• Use bundle exec rspec or bin/rspec consistently.
• Do not exclude the test group when CI needs to run tests.
• Install the bundle before invoking rspec.

Frequently asked questions

Related guides

References

• Bundler documentation
• GitHub Actions documentation