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}: %{message}

What it means

The yaml format's intern deserializes with Puppet::Util::Yaml.safe_load restricted to an allow-list of Puppet model classes (facts, node, report, resource, catalog). When safe_load raises YamlLoadError — malformed YAML, disallowed tags or classes outside the allow-list — it is re-raised as FormatError naming the target class and the underlying Psych message. This is Puppet's safe-deserialization boundary for YAML.

Source

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

  end
end

Puppet::Network::FormatHandler.create_serialized_formats(:yaml) do
  def allowed_yaml_classes
    @allowed_yaml_classes ||= [
      Puppet::Node::Facts,
      Puppet::Node,
      Puppet::Transaction::Report,
      Puppet::Resource,
      Puppet::Resource::Catalog
    ]
  end

  def intern(klass, text)
    data = Puppet::Util::Yaml.safe_load(text, allowed_yaml_classes)
    data_to_instance(klass, data)
  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 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)

View on GitHub (pinned to e227c27540)

Solutions

1. Read %{message} — it carries the Psych cause and location; fix or regenerate the document accordingly.
2. If the document legitimately holds a Puppet model class, it must be one of the allow-listed ones (Puppet::Node::Facts, Puppet::Node, Puppet::Transaction::Report, Puppet::Resource, Puppet::Resource::Catalog); re-serialize accordingly.
3. Delete corrupted cache files (state/yaml/*) and let Puppet rebuild them.
4. Regenerate the YAML with the same Puppet version that will read it.

Example fix

# before — YAML smuggles an arbitrary object
--- !ruby/object:Backdoor

# after — plain data the safe loader accepts
---
name: web1.example.com
values:
  uptime_days: 42

begin
  data = Puppet::Util::Yaml.safe_load(text, [])
rescue Puppet::Util::Yaml::YamlLoadError => e
  raise ArgumentError, "untrusted or invalid YAML: #{e.message}"
end
# only then hand the text to the format
obj = Klass.convert_from(:yaml, text)

begin
  obj = Klass.convert_from(:yaml, text)
rescue Puppet::Network::FormatHandler::FormatError => e
  # e.message: 'Serialized YAML did not contain a valid instance of ...' plus the cause
  raise
end

When it happens

Trigger: Puppet::Node::Facts.convert_from(:yaml, corrupt_or_untrusted) or catalog/report interning where the document contains a disallowed ruby class (e.g. !ruby/object:MyThing), unknown aliases, or plain syntax errors — typically data produced by a different version or hand-edited.

Common situations: Hand-edited or truncated cache files under the agent state directory; YAML produced by a newer/older Psych with different tag handling; attempts to smuggle arbitrary objects through facts/reports; cached YAML migrated across Puppet major versions.

Related errors

• Could not intern from %{format}: %{err}
• Could not intern_multiple from %{format}: %{err}
• Serialized YAML did not contain a collection of instances wh
• Serialized YAML did not contain a valid instance of %{klass}
• #{path}: #{detail.message}

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