puppetlabs/puppet · error · ArgumentError

Unsupported checksum type %{checksum_type}

Error message

Unsupported checksum type %{checksum_type}

What it means

Every filebucket request key has the form 'algorithm/hexdigest' (optionally '/original/path'). request_to_checksum_and_path splits the key and hard-compares the algorithm token against the node's digest_algorithm setting; any other prefix raises ArgumentError 'Unsupported checksum type'. The digest must then be lowercase hex of the algorithm's exact length (md5 = 32 chars, sha256 = 64 chars), checked via <type>_hex_length.

Source

Thrown at lib/puppet/indirector/file_bucket_file/file.rb:209

            end
          else
            copy_bucket_file_to_contents_file(contents_file, bucket_file)
          end

          unless path_match(f, files_original_path)
            f.seek(0, IO::SEEK_END)
            f.puts(files_original_path)
          end
        end
      end
    end

    def request_to_checksum_and_path(request)
      checksum_type, checksum, path = request.key.split(%r{/}, 3)
      if path == '' # Treat "md5/<checksum>/" like "md5/<checksum>"
        path = nil
      end
      raise ArgumentError, _("Unsupported checksum type %{checksum_type}") % { checksum_type: checksum_type.inspect } if checksum_type != Puppet[:digest_algorithm]

      expected = method(checksum_type + "_hex_length").call
      raise _("Invalid checksum %{checksum}") % { checksum: checksum.inspect } if checksum !~ /^[0-9a-f]{#{expected}}$/

      [checksum, path]
    end

    # @return [Object] Opaque path as constructed by the Puppet::FileSystem
    #
    def path_for(bucket_path, digest, subfile = nil)
      bucket_path ||= Puppet[:bucketdir]

      dir     = ::File.join(digest[0..7].split(""))
      basedir = ::File.join(bucket_path, dir, digest)

      Puppet::FileSystem.pathname(subfile ? ::File.join(basedir, subfile) : basedir)
    end

View on GitHub (pinned to e227c27540)

Solutions

1. Check the setting on the node making the request: puppet config print digest_algorithm, and use that algorithm in the key/URI prefix.
2. Standardize by setting digest_algorithm=sha256 in the [main] section of puppet.conf on every node (agents and servers) if you migrate off md5.
3. Fix hand-built keys to algorithm + '/' + lowercase hex digest of correct length.
4. Remember old backups written under md5 remain addressed with md5/ keys even after switching.

Example fix

# before: node has digest_algorithm = md5
Puppet::FileBucket::File.indirection.find('sha256/' + sha256_hex)
# ArgumentError: Unsupported checksum type "sha256"

# after: align algorithm on both sides
# puppet.conf: [main] digest_algorithm = sha256
Puppet::FileBucket::File.indirection.find('sha256/' + sha256_hex)

algo = Puppet[:digest_algorithm]
hex = digest.downcase
len = { 'md5' => 32, 'sha256' => 64 }.fetch(algo)
raise ArgumentError, 'wrong hex length for ' + algo unless hex =~ /\A[0-9a-f]{#{len}}\z/
key = algo + '/' + hex

def valid_bucket_key?(key)
  algo, hex = key.to_s.split('/', 2)
  return false unless algo == Puppet[:digest_algorithm]
  len = { 'md5' => 32, 'sha256' => 64 }.fetch(algo, 0)
  hex.to_s =~ /\A[0-9a-f]{#{len}}\z/ ? true : false
end

When it happens

Trigger: Sending a 'sha256/...' key to a node whose digest_algorithm is md5 (the classic default), or 'md5/...' to a node configured for sha256; Ruby callers hand-building request keys; agents and servers configured with different digest_algorithm values during a backup/restore.

Common situations: Fleets mid-migration from md5 to sha256; FIPS environments where md5 is unavailable; puppet.conf drift between agent and server; scripts hardcoding 'md5/' prefixes.

Related errors

• File not found
• Unable to find a common checksum type between agent '%{agent
• Existing backup and new file have different content but same
• MD5 is not supported in FIPS mode
• Unable to verify existing FileBucket backup at '%{path}'.

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