What causes "Invalid 'name' field in metadata.json: %{err}" in puppetlabs/puppet?

Set name to ' - ' or ' / ', e.g. 'puppetlabs-stdlib', all lowercase

puppetlabs/puppet · error · ArgumentError

Invalid 'name' field in metadata.json: %{err}

Error message

Invalid 'name' field in metadata.json: %{err}

What it means

Puppet::ModuleTool::Metadata#validate_name enforces Forge naming: the name must match \A[a-z0-9]+[-/][a-z][a-z0-9_]*\Z — a non-empty namespace, a '-' or '/' separator, and a module part starting with a letter, alphanumeric/underscore only. Any other shape raises ArgumentError with a reason selected by the case chain (missing namespace, illegal characters, bad start, bad namespace). It runs whenever metadata.json is parsed (line 127).

Source

Thrown at lib/puppet/module_tool/metadata.rb:190

    # Validates that the given module name is both namespaced and well-formed.
    def validate_name(name)
      return if name =~ %r{\A[a-z0-9]+[-/][a-z][a-z0-9_]*\Z}i

      namespace, modname = name.split(%r{[-/]}, 2)
      modname = :namespace_missing if namespace == ''

      err = case modname
            when nil, '', :namespace_missing
              _("the field must be a namespaced module name")
            when /[^a-z0-9_]/i
              _("the module name contains non-alphanumeric (or underscore) characters")
            when /^[^a-z]/i
              _("the module name must begin with a letter")
            else
              _("the namespace contains non-alphanumeric characters")
            end

      raise ArgumentError, _("Invalid 'name' field in metadata.json: %{err}") % { err: err }
    end

    # Validates that the version string can be parsed as per SemVer.
    def validate_version(version)
      return if SemanticPuppet::Version.valid?(version)

      err = _("version string cannot be parsed as a valid Semantic Version")
      raise ArgumentError, _("Invalid 'version' field in metadata.json: %{err}") % { err: err }
    end

    # Validates that the given _value_ is a symbolic name that starts with a letter
    # and then contains only letters, digits, or underscore. Will raise an ArgumentError
    # if that's not the case.
    #
    # @param value [Object] The value to be tested
    def validate_data_provider(value)
      if value.is_a?(String)
        unless value =~ /^[a-zA-Z][a-zA-Z0-9_]*$/

View on GitHub (pinned to e227c27540)

Solutions

Set name to '<author>-<module>' or '<author>/<module>', e.g. 'puppetlabs-stdlib', all lowercase
Make the module part start with a letter and use only [a-z0-9_]
Rename the module directory to match the short name (stdlib for puppetlabs-stdlib) so Puppet resolves it correctly
Re-validate by re-running `puppet module build` or parsing the file with Puppet::ModuleTool::Metadata

Example fix

// before - metadata.json
"name": "stdlib",

// after
"name": "puppetlabs-stdlib",

Defensive patterns

Strategy: validation

Validate before calling

VALID_NAME = /\A[a-z0-9]+[-\/][a-z][a-z0-9_]*\Z/i

name = JSON.parse(File.read('metadata.json'))['name']
abort "invalid module name '#{name}' — expected '<author>-<module>' or '<author>/<module>'" unless name =~ VALID_NAME

Try / catch

begin
  Puppet::ModuleTool::Metadata.from_hash('name' => raw_name)
rescue ArgumentError => e
  raise unless e.message =~ /Invalid 'name' field/
  raw_name = "acme-#{raw_name.tr('^a-zA-Z0-9_', '')}".downcase  # repair, then retry
  retry
end

Prevention

Always generate new modules with `puppet module generate <author>-<name>` to get a valid skeleton
Keep the module name lowercase, namespaced, and matching the directory short name
Add a metadata.json lint step (metadata-json-lint) to CI

When it happens

Trigger: A metadata.json with name 'stdlib' (no namespace), 'puppet-labs/stdlib' or 'puppet 4-stdlib' (illegal characters), 'puppetlabs/4stdlib' (module part must begin with a letter), or 'puppet labs/stdlib' (space in namespace).

Common situations: Hand-writing metadata.json without the author prefix; copy-paste from Rubygems-style names ('puppetlabs-stdlib' is fine but 'stdlib' alone is not); names containing hyphens in the module part; metadata written by generators that never validated the format.

Related errors

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