voormedia/rails-erd · error

Saving diagram failed! Verify that Graphviz is installed and

Error message

Saving diagram failed!
Verify that Graphviz is installed and in your path, or use filetype=dot.

What it means

The second rescue in the same save block (graphviz.rb:226-229) catches StandardError -- in practice Errno::ENOENT -- raised when ruby-graphviz tries to execute the 'dot' executable and cannot find it. Unlike the RuntimeError branch, dot never ran: there is no dot binary on the PATH of the process generating the diagram. The message directs you to install Graphviz or, if that is impossible, use filetype=dot.

Source

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

        graph[:splines] = options.splines unless options.splines.nil?

        # Setup notation options.
        extend self.class.const_get(options.notation.to_s.capitalize.to_sym)
      end

      save do
        raise "Saving diagram failed!\nOutput directory '#{File.dirname(filename)}' does not exist." unless File.directory?(File.dirname(filename))

        begin
          # GraphViz doesn't like spaces in the filename
          graph.output(filetype => filename.gsub(/\s/,"_"))
          filename
        rescue RuntimeError => e
          raise "Saving diagram failed!\nGraphviz produced errors. Verify it " +
                  "has support for filetype=#{options.filetype}, or use " +
                  "filetype=dot.\nOriginal error: #{e.message.split("\n").last}"
        rescue StandardError => e
          raise "Saving diagram failed!\nVerify that Graphviz is installed " +
                  "and in your path, or use filetype=dot."
        end
      end

      each_entity do |entity, attributes|
        if options[:cluster] && entity.namespace
          cluster_name = "cluster_#{entity.namespace}"
          cluster_options = CLUSTER_ATTRIBUTES.merge(label: entity.namespace)
          cluster = graph.get_graph(cluster_name) ||
                    graph.add_graph(cluster_name, cluster_options)

          draw_cluster_node cluster, entity.name, entity_options(entity, attributes)
        else
          draw_node entity.name, entity_options(entity, attributes)
        end
      end

      each_specialization do |specialization|

View on GitHub (pinned to dae6e52018)

Solutions

  1. Install Graphviz so 'dot' is on PATH: macOS brew install graphviz; Debian/Ubuntu sudo apt-get install graphviz; Alpine apk add graphviz; Fedora sudo dnf install graphviz
  2. Verify in the SAME environment that runs rails-erd: which dot && dot -V
  3. If you cannot install system packages, switch to generator: mermaid, which writes the .mmd file in pure Ruby with no external binary

Example fix

# before
bundle exec rake erd
# => RuntimeError: ... Verify that Graphviz is installed and in your path ...

# after (Dockerfile / CI)
RUN apt-get update && apt-get install -y graphviz
bundle exec rake erd
Defensive patterns

Strategy: validation

Validate before calling

def dot_available?
  system('dot', '-V', out: File::NULL, err: File::NULL)
end

if dot_available?
  RailsERD::Diagram::Graphviz.create
else
  RailsERD::Diagram::Mermaid.create
end

Try / catch

begin
  RailsERD::Diagram::Graphviz.create
rescue StandardError => e
  raise unless e.message.include?('Verify that Graphviz is installed')
  RailsERD::Diagram::Mermaid.create
end

Prevention

When it happens

Trigger: graph.output spawning 'dot' when the Graphviz package is not installed; PATH not containing dot in the executing context (cron, systemd, Capistrano, IDE shells, Docker images without graphviz); dot present but not executable.

Common situations: Diagrams generate locally (brew install graphviz) but CI or deploy has no graphviz package; rake erd inside a slim Docker image; PATH stripped or different under cron/systemd units; new team members who never installed Graphviz.

Related errors

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