puppetlabs/puppet · error · ArgumentError

The pcore version for TypeSet '#{@name}' is not understood b

Error message

The pcore version for TypeSet '#{@name}' is not understood by this runtime. Expected range #{Pcore::PARSABLE_PCORE_VERSIONS}, got #{@pcore_version}

What it means

A TypeSet's serialized definition carries a pcore_version stating which Pcore schema dialect it was written for. On load, _pcore_init_from_hash parses it and checks membership in Pcore::PARSABLE_PCORE_VERSIONS (parsed from '1.x' in lib/puppet/pops/pcore.rb:21); anything outside the runtime's supported range raises ArgumentError naming the TypeSet, the expected range, and the version found.

Source

Thrown at lib/puppet/pops/types/p_type_set_type.rb:118

    else
      # Creation using "type XXX = TypeSet[{}]". This means that the name is given
      @name = TypeAsserter.assert_instance_of('TypeSet name', Pcore::TYPE_QUALIFIED_REFERENCE, name_or_init_hash)
      @name_authority = TypeAsserter.assert_instance_of('TypeSet name_authority', Pcore::TYPE_URI, name_authority, true)
      @init_hash_expression = init_hash_expression
    end
  end

  # @api private
  def _pcore_init_from_hash(init_hash)
    TypeAsserter.assert_instance_of('TypeSet initializer', TYPE_TYPESET_I12N, init_hash)

    # Name given to the loader have higher precedence than a name declared in the type
    @name ||= init_hash[KEY_NAME].freeze
    @name_authority ||= init_hash[KEY_NAME_AUTHORITY].freeze

    @pcore_version = PSemVerType.convert(init_hash[Pcore::KEY_PCORE_VERSION]).freeze
    unless Pcore::PARSABLE_PCORE_VERSIONS.include?(@pcore_version)
      raise ArgumentError,
            "The pcore version for TypeSet '#{@name}' is not understood by this runtime. Expected range #{Pcore::PARSABLE_PCORE_VERSIONS}, got #{@pcore_version}"
    end

    @pcore_uri = init_hash[Pcore::KEY_PCORE_URI].freeze
    @version = PSemVerType.convert(init_hash[KEY_VERSION])
    @types = init_hash[KEY_TYPES] || EMPTY_HASH
    @types.freeze

    # Map downcase names to their camel-cased equivalent
    @dc_to_cc_map = {}
    @types.keys.each { |key| @dc_to_cc_map[key.downcase] = key }

    refs = init_hash[KEY_REFERENCES]
    if refs.nil?
      @references = EMPTY_HASH
    else
      ref_map = {}
      root_map = Hash.new { |h, k| h[k] = {} }

View on GitHub (pinned to e227c27540)

Solutions

1. Run the typeset on a runtime that supports its pcore_version: upgrade Puppet on the loading node
2. Or regenerate the typeset with the target runtime so it emits a supported pcore_version
3. For hand-written typesets, set pcore_version to a value inside the supported range (e.g. '1.0.0') and adjust any schema features that are not 1.x

Example fix

# before (typeset JSON/pcore data)
{
  "name": "MyApp",
  "pcore_version": "2.0.0",
  "types": { ... }
}

# after
{
  "name": "MyApp",
  "pcore_version": "1.0.0",
  "types": { ... }
}

# before loading a typeset, check its pcore_version against the runtime's range
supported = Puppet::Pops::Pcore::PARSABLE_PCORE_VERSIONS
version = SemanticPuppet::Version.parse(typeset['pcore_version'] || '1.0.0')
raise "typeset #{typeset['name']} requires pcore #{version}, runtime supports #{supported}" unless supported.include?(version)

def parsable_pcore_version?(typeset)
  Puppet::Pops::Pcore::PARSABLE_PCORE_VERSIONS.include?(
    SemanticPuppet::Version.parse(typeset['pcore_version'] || '1.0.0')
  )
end

begin
  type_set.resolve(loader)
rescue ArgumentError => e
  raise unless e.message =~ /pcore version for TypeSet/
  raise "version skew: regenerate the typeset or upgrade Puppet. #{e.message}"
end

When it happens

Trigger: Loading a TypeSet whose pcore_version is e.g. '2.0.0' (written by a newer runtime) or '0.9.0' (pre-release dialect) on a Puppet runtime whose Pcore only understands 1.x. Happens when typesets are copied between installations, exported by puppet-strings bolt/pcore tooling of a different version, or hand-written with a wrong version string.

Common situations: Version skew: a module or typeset generated on a newer Puppet master is deployed to older agents; hand-authored .pp type files with an explicit pcore_version; upgrading Puppet and forgetting that exported typesets pin their schema version.

Related errors

• Puppet #{Puppet.version} requires Ruby #{Puppet::OLDEST_RECO
• Data Type Load Error for type '%{type_name}': %{message}
• a data type must have an interface
• a data type can only have one interface
• a data type can only have one implementation

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