voormedia/rails-erd · error · LoadError

The ruby-graphviz gem is required for Graphviz output. Add `

Error message

The ruby-graphviz gem is required for Graphviz output. Add `gem 'ruby-graphviz'` to your Gemfile, or use `generator: mermaid` instead.

What it means

rails-erd's Graphviz generator needs the ruby-graphviz gem to build diagrams. Since v2.0 the gem is optional: the require at the top of lib/rails_erd/diagram/graphviz.rb is wrapped in begin/rescue LoadError, so the failure is deferred to diagram generation, where the setup callback finds no GraphViz constant (defined?(GraphViz) is false, graphviz.rb:189-193) and raises LoadError with install instructions. It means the process running 'rake erd' or RailsERD::Diagram::Graphviz.create has no ruby-graphviz loaded.

Source

Thrown at lib/rails_erd/diagram/graphviz.rb:191

            options[:arrowtail] = relationship.many_to? ? "vee" : "none"

            ranges = [relationship.cardinality.destination_range, relationship.cardinality.source_range].map do |range|
              if range.min == range.max
                "#{range.min}"
              else
                "#{range.min}..#{range.max == Domain::Relationship::N ? "∗" : range.max}"
              end
            end
            options[:headlabel], options[:taillabel] = *ranges
          end
        end
      end

      attr_accessor :graph

      setup do
        unless defined?(GraphViz)
          raise LoadError, "The ruby-graphviz gem is required for Graphviz output. " \
            "Add `gem 'ruby-graphviz'` to your Gemfile, or use `generator: mermaid` instead."
        end

        self.graph = GraphViz.digraph(domain.name)

        # Set all default attributes.
        GRAPH_ATTRIBUTES.each { |attribute, value| graph[attribute] = value }
        NODE_ATTRIBUTES.each  { |attribute, value| graph.node[attribute] = value }
        EDGE_ATTRIBUTES.each  { |attribute, value| graph.edge[attribute] = value }

        # Switch rank direction if we're creating a vertically oriented graph.
        graph[:rankdir] = (options.orientation == "vertical") ? :LR : :TB

        # Title of the graph itself.
        graph[:label] = "#{title}\\n\\n" if title

        # Style of splines
        graph[:splines] = options.splines unless options.splines.nil?

View on GitHub (pinned to dae6e52018)

Solutions

Add gem 'ruby-graphviz' to your Gemfile (the gem is named ruby-graphviz, the require is 'graphviz') and run bundle install
Verify it loads in the same context: bundle exec ruby -e "require 'graphviz'; puts defined?(GraphViz)"
If you cannot add the gem, switch generators: rake erd generator=mermaid (or RailsERD.options[:generator] = :mermaid), which is pure Ruby and needs no extra gem

Example fix

# before (Gemfile)
gem 'rails-erd'
# $ bundle exec rake erd
# => LoadError: The ruby-graphviz gem is required for Graphviz output...

# after (Gemfile)
gem 'rails-erd'
gem 'ruby-graphviz'
# $ bundle install && bundle exec rake erd

Defensive patterns

Strategy: validation

Validate before calling

begin
  require 'graphviz'
rescue LoadError
  # fall back before ever touching the Graphviz diagram
end

RailsERD::Diagram::Graphviz.create if defined?(GraphViz)

Type guard

def graphviz_available?
  defined?(GraphViz) == 'constant'
end

Try / catch

begin
  RailsERD::Diagram::Graphviz.create
rescue LoadError => e
  warn e.message
  RailsERD::Diagram::Mermaid.create
end

Prevention

Declare ruby-graphviz in the Gemfile wherever generator: :graphviz is the default
Preflight CI with bundle exec ruby -e "require 'graphviz'" before the erd rake task
Remember the gem name is ruby-graphviz but the require is 'graphviz'

When it happens

Trigger: Running the default Graphviz generator -- 'rake erd', RailsERD::Diagram::Graphviz.create(options), or Graphviz.new(domain).create -- in a process where require 'graphviz' failed: gem absent from the Gemfile, present but never installed (no bundle install), or generator switched back to :graphviz after runs with generator: :mermaid.

Common situations: Upgrading rails-erd from 1.x (ruby-graphviz was a hard dependency) to 2.x where it became optional; fresh clones or CI images that never bundle the optional gem; mixing up gem names (gem 'graphviz' vs gem 'ruby-graphviz'); switching an erd config back to the default generator on a machine that only ever installed deps for mermaid output.

Related errors

AI-assisted analysis of voormedia/rails-erd@dae6e52018 (2026-08-23). Data as JSON: /api/errors/c9cb87104c0c16d4. Report an issue: GitHub.