puppetlabs/puppet · error · ArgumentError

Invalid version format: %{version} (Semantic Versions are ac

Error message

Invalid version format: %{version} (Semantic Versions are acceptable: http://semver.org)

What it means

Application#parse_filename raises ArgumentError when the version substring extracted from the tarball filename fails SemanticPuppet::Version.valid?. The regex only guarantees digits.digits.digits at the start of the version segment; this second check requires the whole segment (including any prerelease/build suffix) to be a valid semantic version per semver.org.

Source

Thrown at lib/puppet/module_tool/applications/application.rb:84

        @metadata
      end

      def load_metadata!
        @metadata = nil
        metadata(true)
      end

      def parse_filename(filename)
        match = /^((.*?)-(.*?))-(\d+\.\d+\.\d+.*?)$/.match(File.basename(filename, '.tar.gz'))
        if match
          module_name, author, shortname, version = match.captures
        else
          raise ArgumentError, _("Could not parse filename to obtain the username, module name and version.  (%{release_name})") % { release_name: @release_name }
        end

        unless SemanticPuppet::Version.valid?(version)
          raise ArgumentError, _("Invalid version format: %{version} (Semantic Versions are acceptable: http://semver.org)") % { version: version }
        end

        {
          :module_name => module_name,
          :author => author,
          :dir_name => shortname,
          :version => version
        }
      end
    end
  end
end

View on GitHub (pinned to e227c27540)

Solutions

Use strict semver MAJOR.MINOR.PATCH with optional '-' prerelease and '+' build identifiers: rename/repack as 'author-mod-1.0.0-rc.1.tar.gz'.
Drop the fourth version segment or move it into build metadata (e.g. '1.2.3+4').
Fix leading zeros in numeric prerelease parts ('-RC.01' -> '-RC.1').
Rebuild the module with `puppet module build` after correcting 'version' in metadata.json.

Example fix

# before
myteam-webapp-1.2.3.4.tar.gz

# after
myteam-webapp-1.2.3+4.tar.gz

Defensive patterns

Strategy: validation

Validate before calling

require 'semantic_puppet'

version = filename_segment.split('-').last
abort 'version must be semantic (x.y.z[-pre][+build])' unless SemanticPuppet::Version.valid?(version)

Type guard

def semver_string?(s)
  SemanticPuppet::Version.valid?(s.to_s)
end

Try / catch

begin
  app.parse_filename(tarball)
rescue ArgumentError => e
  retry_with_renamed = e.message.include?('Invalid version format')
  raise
end

Prevention

Keep module versions strict semver (three numeric segments, optional -pre/+build).
Validate metadata.json 'version' with SemanticPuppet::Version.valid? at build time, not after packaging.
Avoid date-based or four-part version schemes for Puppet modules.

When it happens

Trigger: A filename version segment like '1.0.0.0' (four segments), '1.02.3' (leading zero), '2.0.0-RC.01+build..2' (malformed prerelease/build metadata with empty identifiers or leading zeros), or '1.0.0-alpha..1'. The regex matched, so the tarball reached version validation, but SemanticPuppet rejects the string.

Common situations: Custom versioning schemes (date-based '2023.01.15.1', four-part .NET-style versions) in internally packaged modules; handcrafted prerelease tags with invalid characters; snapshot builds appending timestamps after '+'.

Related errors

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