Bundler "Gem::FilePermissionError" (EACCES) in CI

By Kaveh Alemi·Latchkey

Bundler tried to install gems into the system gem directory, which the CI user cannot write to, so it raises Gem::FilePermissionError. The fix is to install into a user-writable path with bundle config path.

What this error means

bundle install fails with "Gem::FilePermissionError: You do not have write permissions for the /usr/local/lib/ruby/gems/... directory" on a container or runner where the job runs as a non-root user.

Gem::FilePermissionError: You do not have write permissions for the
/usr/local/lib/ruby/gems/3.3.0 directory.

Common causes

Installing into the system gem directory

Without a configured path, Bundler targets the global gem home, which a non-root CI user cannot write.

A container image running as an unprivileged user

The image drops root for safety, so system-wide gem installs are denied.

How to fix it

Install into a project-local path

1. Set the bundle path to a writable directory in the workspace.
2. Run bundle install so gems land in that path.
3. Cache the same path so installs are fast and consistent.

bundle config set --local path vendor/bundle
bundle install

Set the path via env for the whole job

BUNDLE_PATH applies to every Bundler command in the step without repeating the config.

env:
  BUNDLE_PATH: vendor/bundle

How to prevent it

• Always set bundle path to a project-local directory in CI.
• Cache vendor/bundle keyed on Gemfile.lock for speed.
• Avoid sudo gem install in CI; keep gems in the workspace.

Frequently asked questions

Related guides

References

• Bundler documentation
• GitHub Actions documentation