puppetlabs/puppet · error · Puppet::Network::FormatHandler::FormatError

Serialized YAML did not contain a valid instance of %{klass}

Error message

Serialized YAML did not contain a valid instance of %{klass}

What it means

After YAML loads, data_to_instance accepts a datum only if it already is an instance of the target class or is a Hash passable to klass.from_data_hash. Any other type — String, Symbol, Integer, Array for non-array classes — raises FormatError 'Serialized YAML did not contain a valid instance of %{klass}'. The document loaded fine; its elements are the wrong shape for the class being interned.

Source

Thrown at lib/puppet/network/formats.rb:62

  def intern_multiple(klass, text)
    data = Puppet::Util::Yaml.safe_load(text, allowed_yaml_classes)
    unless data.respond_to?(:collect)
      raise Puppet::Network::FormatHandler::FormatError, _("Serialized YAML did not contain a collection of instances when calling intern_multiple")
    end

    data.collect do |datum|
      data_to_instance(klass, datum)
    end
  rescue Puppet::Util::Yaml::YamlLoadError => e
    raise Puppet::Network::FormatHandler::FormatError, _("Serialized YAML did not contain a valid instance of %{klass}: %{message}") % { klass: klass, message: e.message }
  end

  def data_to_instance(klass, data)
    return data if data.is_a?(klass)

    unless data.is_a? Hash
      raise Puppet::Network::FormatHandler::FormatError, _("Serialized YAML did not contain a valid instance of %{klass}") % { klass: klass }
    end

    klass.from_data_hash(data)
  end

  def render(instance)
    instance.to_yaml
  end

  # Yaml monkey-patches Array, so this works.
  def render_multiple(instances)
    instances.to_yaml
  end

  def supported?(klass)
    true
  end
end

View on GitHub (pinned to e227c27540)

Solutions

1. Make each document/element a Hash matching the class's from_data_hash schema, or a real instance (serialize the object itself).
2. Fix the producer to dump the object's data hash, not a field of it.
3. Confirm the class being interned matches the document kind (a facts hash for Puppet::Node::Facts, etc.).
4. Update fixtures after any from_data_hash schema change.

Example fix

# before — widgets.yaml contains '--- widget-42'
Widget.convert_from(:yaml, File.read('widgets.yaml')) # not a Hash → error

# after
# widgets.yaml:
# ---
# id: 42
# name: widget-42
Widget.convert_from(:yaml, File.read('widgets.yaml'))

data = Puppet::Util::Yaml.safe_load(text, [])
raise ArgumentError, 'document must be a data hash' unless data.is_a?(Hash) || data.is_a?(Klass)
obj = Klass.convert_from(:yaml, text)

def internable_yaml?(data, klass)
  data.is_a?(klass) || data.is_a?(Hash)
end

begin
  obj = Klass.convert_from(:yaml, text)
rescue Puppet::Network::FormatHandler::FormatError => e
  raise unless e.message.include?('valid instance')
  # shape mismatch — inspect the document and regenerate it as a data hash
end

When it happens

Trigger: Klass.convert_from(:yaml, '--- just-a-string'); intern_multiple over a sequence of scalars ('- 1', '- 2'); a producer serializing the wrong field (dumping obj.name instead of obj.to_data_hash).

Common situations: Test fixtures containing scalar YAML; producers dumping a field instead of the data hash; schema drift after from_data_hash changed across Puppet versions; consumers interning a class that does not match the document kind.

Related errors

• Serialized YAML did not contain a collection of instances wh
• Could not intern from %{format}: %{err}
• Could not intern_multiple from %{format}: %{err}
• Serialized YAML did not contain a valid instance of %{klass}
• --values_file option must evaluate to a Hash or undef/nil, g

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