Fixing require LoadError as an example for the matrix gem

Reading time: 3 minutes

cannot load such file matrix LoadError

Some gems like matrix or rexml were added at some point to ruby becoming so-called default gems. But they may be removed from being default in newer ruby versions, resulting in broken builds like for us with prawn:

bin/rails c
'require': cannot load such file -- matrix (LoadError)

In most such cases you have to update the used gem (for us prawn) to a newer version, which defines the missing gem as required for this ruby version.

If there is no update, you can mostly fix this by adding the missing gem to your Gemfile using a command:

bundle add matrix
bundle install

Or just add an entry to your Gemfile:

+ # missing dependency for prawn since ruby 3.1
+ gem "matrix"
gem "prawn"

And run:

bundle install

Now your project should may work again.

Some background around default and bundled gems

Default gems are gems that are part of Ruby and you can always require them directly. The special thing is, you can’t remove them from your ruby installation.

Bundled gems are normal gems that are installed on Ruby installation. But they can be removed at any time by yourself or someone else.

The matrix gem was added to Ruby 2.6.0 as default Ruby gem and became a bundled gem since Ruby 3.1.0.

As most installations are using the default Ruby setup, most developers don’t even notice such changes. But if you are using a customized Docker Image or a special development machine, where such dependencies were removed for some reason (like security problems), you have to fix it.

Fixing by creating a pull request for a gem

The best thing is to create a pull request for the related project with something like this to the .gemspec file:

+ spec.add_dependency('matrix', '~> 0.4')

The problem with this change is, that now your project can’t be installed on Ruby older than 3.1.0, as the previous versions have an older matrix gem version or maybe require an older gem version in their projects (see sdtgems.org) and prawn issue #1304.

A better fix would add the dependency only on Ruby versions newer than 3.1:

+ spec.add_dependency("matrix", "~> 0.4") if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("3.1")

But the problem is, this fix may take some time to get to a new release like it is for prawn since 2020.

Move on to a new gem (if you can)

If you do have not much code dependency or you can handle it, maybe it is time to move on to a better-maintained project by migrating your code to another solution. I’ll try hexapdf for my next PDF-related work.

At some point, you can maybe fork a stale project and try to maintain it for yourself or even create a fork and start a new project based on the code of the old one.

Summary

Handling dependencies in any manner may become hard at some point. Ruby has several solutions to get back on track or have a fix, which may gain you some time to find a better solution.

In most cases, it is enough to add such a gem to your Gemfile and get your project running again like it was for me with prawn, Ruby 3.2, and the missing matrix gem in a Docker image by running:

bundle add matrix
bundle install

But prawn is now on a watch list as it may become at some point a road blocker if the maintainer(s) don’t find a solution to go on.

Newsletter

See Also

Tags