Saving diagram failed! Graphviz produced errors. Verify it h

Error message

Saving diagram failed!
Graphviz produced errors. Verify it has support for filetype=#{options.filetype}, or use filetype=dot.
Original error: #{e.message.split("\n").last}

What it means

Once the directory check passes, save calls graph.output(filetype => filename) (graphviz.rb:218-221), which shells out to the Graphviz 'dot' binary. ruby-graphviz raises RuntimeError when dot exits non-zero; rails-erd rescues it and re-raises with the requested filetype plus the last line of dot's stderr (graphviz.rb:222-225). So dot ran but rejected the request -- most often the installed Graphviz build lacks the renderer for options.filetype (default :pdf), or dot choked on something in the generated graph.

Source

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

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

        # Style of splines
        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)

View on GitHub (pinned to dae6e52018)

Solutions

Reproduce the real error: generate with filetype=dot, then run dot -T<fmt> ERD.dot manually to read dot's full stderr
List the formats your build supports: dot -T?
If the format is unsupported, install a full Graphviz build (apt-get install -y graphviz on a full base image, or add the cairo/pango deps on Alpine) or fall back to a supported format such as pdf or dot

Example fix

# before (Alpine CI)
rake erd filetype=png
# => RuntimeError: ... Verify it has support for filetype=png ...

# after (Dockerfile)
RUN apk add --no-cache graphviz ttf-dejavu
# or fall back to a format the build supports:
rake erd filetype=dot

Defensive patterns

Strategy: try-catch

Validate before calling

fmt = :png
ok = system('dot', '-T' + fmt.to_s, '-o', '/dev/null', in: '/dev/null', err: File::NULL)
RailsERD::Diagram::Graphviz.create(filetype: ok ? fmt : :dot)

Try / catch

begin
  RailsERD::Diagram::Graphviz.create(filetype: :png)
rescue RuntimeError => e
  raise unless e.message.include?('Graphviz produced errors')
  warn 'falling back to filetype=dot'
  RailsERD::Diagram::Graphviz.create(filetype: :dot)
end

Prevention

Assert that dot -T<filetype> exits 0 in CI before the erd step
Treat filetype=dot as the portable baseline and render to png/pdf only where a full Graphviz is guaranteed
Pin a full-featured graphviz package in Dockerfiles (add cairo/pango deps on Alpine)

When it happens

Trigger: rake erd filetype=png / filetype=svg / filetype=pdf against a Graphviz build compiled without that renderer (typical on Alpine or debian-slim images lacking cairo/pango); a typo'd filetype such as filetype=pgn; any condition that makes 'dot -T<fmt>' exit non-zero (missing font, bad attribute).

Common situations: Diagram renders on the dev machine (full Homebrew/apt graphviz) but fails in Alpine or slim CI images; distro package changes dropping an optional format; switching filetype from pdf to png on a server; ERD_FILETYPE set in an ignored environment file.

Related errors

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