cannot load such file -- X from a bundled require in CI

By Kaveh Alemi·Latchkey

A gem that is in the bundle still failed to require because the specific file it loads (often a compiled .so/.bundle) is not present for the runner platform. The gem metadata is there; the artifact is not.

What this error means

A require for an installed gem fails with "cannot load such file -- gem/gem". Distinct from a missing Gemfile entry: bundle list shows the gem, but the compiled or platform-specific file is absent.

LoadError: cannot load such file -- sqlite3/sqlite3_native
        from gems/sqlite3-1.7.0/lib/sqlite3.rb:9:in `require'

Common causes

Native extension not compiled for the platform

The cached gem was built on a different OS/arch (e.g. macOS locally vs Linux on the runner), so the native file is missing on CI.

Precompiled platform gem mismatch

A platform-specific precompiled gem in the lockfile does not match the runner architecture, so the loaded file is absent.

Partial or corrupt restored cache

A restored bundle cache lacks the compiled artifacts because it was keyed without platform/arch.

How to fix it

Rebuild gems on the runner platform

1. Clear the cached bundle and reinstall on the runner so native files compile for it.
2. Add the Linux platform to the lockfile: bundle lock --add-platform x86_64-linux.
3. Ensure build tools (gcc, make, dev headers) are installed for native gems.

bundle lock --add-platform x86_64-linux
rm -rf vendor/bundle && bundle install

Key the cache on platform and Ruby

key: gems-${{ runner.os }}-ruby${{ steps.ruby.outputs.ruby-version }}-${{ hashFiles('Gemfile.lock') }}

How to prevent it

• Add CI platforms to the lockfile with bundle lock --add-platform.
• Include OS/arch/Ruby in the bundle cache key.
• Install native build dependencies before bundle install.

Frequently asked questions

Related guides

References

• Bundler documentation
• GitHub Actions documentation