voormedia/rails-erd · error

Unable to find GraphViz's "dot" executable. Please visit htt

Error message

Unable to find GraphViz's "dot" executable. Please visit https://voormedia.github.io/rails-erd/install.html for installation instructions.

What it means

Error "Unable to find GraphViz's "dot" executable. Please visit https://voormedia.github.io/rails-erd/install.html for installation instructions." thrown in voormedia/rails-erd.

Source

Thrown at lib/rails_erd/tasks.rake:14

module ErdRakeHelper
  def say(message)
    puts message unless Rake.application.options.silent
  end
end

namespace :erd do
  task :check_dependencies do
    if RailsERD.options.generator == :graphviz
      begin
        require 'graphviz/utils'
        include GraphViz::Utils
        unless find_executable("dot", nil)
          raise "Unable to find GraphViz's \"dot\" executable. Please " \
                "visit https://voormedia.github.io/rails-erd/install.html for installation instructions."
        end
      rescue LoadError
        raise "The ruby-graphviz gem is required for Graphviz output. " \
              "Add `gem 'ruby-graphviz'` to your Gemfile, or use `generator=mermaid` instead."
      end
    end
  end

  task :options do
    (RailsERD.options.keys.map(&:to_s) & ENV.keys).each do |option|
      RailsERD.options[option.to_sym] = case ENV[option]
      when "true", "yes" then true
      when "false", "no" then false
      when /,/ then ENV[option].split(/\s*,\s*/)
      when /^\d+$/ then ENV[option].to_i
      else
        if option == 'only'

View on GitHub (pinned to dae6e52018)

Solutions

1. Install GraphViz so the `dot` executable is on your PATH: `brew install graphviz` (macOS), `sudo apt-get install graphviz` (Debian/Ubuntu), or see https://voormedia.github.io/rails-erd/install.html.
2. If GraphViz is installed but not found, add its bin directory to your PATH and re-run `bundle exec rake erd`.
3. Skip GraphViz entirely by using the mermaid generator: `bundle exec rake erd generator=mermaid`.

Example fix

sudo apt-get install graphviz  # or: brew install graphviz

When it happens

Trigger: Raised in the erd:check_dependencies rake task when generator=graphviz (the default) and the GraphViz `dot` executable cannot be found on PATH, i.e. GraphViz is not installed on the system.

Common situations: See trigger scenarios.

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