puppetlabs/puppet · error · Puppet::ParseError

Failed to realize virtual resources %{resources}

Error message

Failed to realize virtual resources %{resources}

What it means

After compilation, fail_on_unevaluated_resource_collections checks every collection (realize() statements and virtual-resource collectors) for unresolved resources. A realize(Virtual_resource['x']) whose target was never declared as a virtual resource anywhere in the compiled code leaves an unresolved entry, and Puppet::ParseError 'Failed to realize virtual resources' lists them. Tag collectors that simply match nothing are fine - only explicitly waited-for refs that never appeared fail.

Source

Thrown at lib/puppet/parser/compiler.rb:426

  # If there are any resource overrides remaining, then we could
  # not find the resource they were supposed to override, so we
  # want to throw an exception.
  def fail_on_unevaluated_overrides
    remaining = @resource_overrides.values.flatten.collect(&:ref)

    unless remaining.empty?
      raise Puppet::ParseError, _("Could not find resource(s) %{resources} for overriding") % { resources: remaining.join(', ') }
    end
  end

  # Make sure there are no remaining collections that are waiting for
  # resources that have not yet been instantiated. If this occurs it
  # is an error (missing resource - it could not be realized).
  #
  def fail_on_unevaluated_resource_collections
    remaining = @collections.collect(&:unresolved_resources).flatten.compact
    unless remaining.empty?
      raise Puppet::ParseError, _("Failed to realize virtual resources %{resources}") % { resources: remaining.join(', ') }
    end
  end

  # Make sure all of our resources and such have done any last work
  # necessary.
  def finish
    evaluate_relationships

    resources.each do |resource|
      # Add in any resource overrides.
      overrides = resource_overrides(resource)
      if overrides
        overrides.each do |over|
          resource.merge(over)
        end

        # Remove the overrides, so that the configuration knows there
        # are none left.

View on GitHub (pinned to e227c27540)

Solutions

1. Declare the resource virtual before realizing: @file { '/etc/app.conf': ... } or include the class that declares it
2. Remove the stray realize() for resources that no longer exist
3. Prefer tag collectors (File<| tag == 'app' |>) which tolerate zero matches

Example fix

// before
realize(File['/etc/app.conf'])

// after
@file { '/etc/app.conf': ensure => file, mode => '0644' }
realize(File['/etc/app.conf'])

begin
  compiler.compile
rescue Puppet::ParseError => e
  if (m = e.message.match(/Failed to realize virtual resources (.+)/))
    unrealized = m[1].split(', ')
  end
  raise
end

When it happens

Trigger: realize(File['/etc/app.conf']) where no @file { '/etc/app.conf': ... } virtual declaration exists; the declaring class was removed or not included; title mismatch between the @declaration and the realize() ref.

Common situations: Deleting a virtual declaration but leaving its realize behind; realize in shared site.pp for resources provided by a class only some nodes include; ref spelling/casing drift.

Related errors

• Could not find resource(s) %{resources} for overriding
• Cannot transform a number to a tag
• Unable to verify the SSL certificate at %{uri}
• No title provided and %{type} is not a valid resource refere
• Could not find resource '%{res}' in parameter '%{param}'

AI-assisted analysis of puppetlabs/puppet@e227c27540 (2026-08-21). Data as JSON: /api/errors/211cdb2591f3a92f. Report an issue: GitHub.