What causes "No entities found; create your models first!" in voormedia/rails-erd?

Confirm models are visible in the same context: bin/rails runner 'puts ActiveRecord::Base.descendants.map(&:name)' -- if empty, run from the app root / fix model loading

voormedia/rails-erd · error

No entities found; create your models first!

Error message

No entities found; create your models first!

What it means

Diagram#generate builds filtered_entities (diagram.rb:232-241): it rejects entities removed by the :only/:exclude filters, STI child entities while options.inheritance is false, polymorphic parents while options.polymorphism is false, and -- by default (disconnected: false) -- every entity with no relationships. If nothing survives the rejects, generation aborts with this RuntimeError. So either the app has no ActiveRecord models discoverable by RailsERD::Domain, or the combination of filters removed every entity.

Source

Thrown at lib/rails_erd/diagram.rb:239

    def save
      instance_eval(&callbacks[:save])
    end

    private

    def callbacks
      @callbacks ||= self.class.send(:callbacks)
    end

    def filtered_entities
      @domain.entities.reject { |entity|
        excluded_by_filter?(entity) or
        !options.inheritance && entity.specialized? or
        !options.polymorphism && entity.generalized? or
        !options.disconnected && entity.disconnected?
      }.compact.tap do |entities|
        raise "No entities found; create your models first!" if entities.empty?
      end
    end

    def filtered_relationships
      @domain.relationships.reject { |relationship|
        (!options.indirect && relationship.indirect?) ||
          # Drop relationships to a model removed by :only/:exclude, otherwise the filtered-out
          # model leaks back in: Graphviz skips such edges implicitly (it only draws an edge when
          # both nodes exist) but Mermaid emits every relationship and renders any named entity.
          excluded_by_filter?(relationship.source) ||
          excluded_by_filter?(relationship.destination)
      }
    end

    # Whether the entity was removed from the diagram by the :only or :exclude option.
    # Used to filter both entities and the relationships that touch them.
    #
    def excluded_by_filter?(entity)

View on GitHub (pinned to dae6e52018)

Solutions

Confirm models are visible in the same context: bin/rails runner 'puts ActiveRecord::Base.descendants.map(&:name)' -- if empty, run from the app root / fix model loading
Check options.only and options.exclude (erd config file or rake erd only=Foo exclude=Bar) for typos or over-broad patterns
Re-include filtered categories: rake erd disconnected=true, or inheritance=true / polymorphism=true for STI- or polymorphic-only schemas
Create at least one model (rails g model ...) before generating the diagram

Example fix

# before -- filter names a model that does not exist
RailsERD::Diagram::Graphviz.create(only: ['Usr'])
# => RuntimeError: No entities found; create your models first!

# after -- fix the name or drop the filter
RailsERD::Diagram::Graphviz.create(only: ['User'])
RailsERD::Diagram::Graphviz.create

Defensive patterns

Strategy: validation

Validate before calling

entities = RailsERD::Domain.generate.entities
visible = entities.reject { |e| e.specialized? || e.generalized? || e.disconnected? }
if visible.empty?
  warn 'Nothing to draw - check :only/:exclude filters and that models are loaded'
else
  RailsERD::Diagram::Graphviz.create
end

Try / catch

begin
  RailsERD::Diagram::Graphviz.create
rescue RuntimeError => e
  raise unless e.message.include?('No entities found')
  warn 'erd skipped: ' + e.message
end

Prevention

Smoke-check ActiveRecord::Base.descendants before generating
Lint only/exclude lists against actual model names in a rake prerequisite
Remember disconnected entities are excluded by default - pass disconnected=true for association-less tables

When it happens

Trigger: 'rake erd' or RailsERD::Diagram.create in an app where ActiveRecord::Base.descendants is empty (fresh app, models never loaded, or running outside the Rails app); only: naming zero or only misspelled model names; exclude: covering every model; a domain consisting solely of STI children with inheritance disabled, or solely of disconnected entities with the default disconnected: false.

Common situations: Running erd on a brand-new app before the first scaffold; invoking the gem from a plain Ruby script or engine that never loads app/models; typos in ERD_ONLY / rake erd only= lists; lookup tables with no associations being silently excluded by the disconnected default; CI environments where eager loading is off.

Related errors

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