puppetlabs/puppet · error · ArgumentError

Cannot manage files of type %{file_type}

Error message

Cannot manage files of type %{file_type}

What it means

Puppet::FileServing::Metadata builds checksums per stat.ftype and handles file, directory, link, fifo, and socket. Any other ftype (Ruby returns 'blockSpecial' or 'characterSpecial' for device nodes) falls into the else branch and raises ArgumentError, because Puppet cannot compute a meaningful checksum/destination for such files.

Source

Thrown at lib/puppet/file_serving/metadata.rb:129

    case stat.ftype
    when "file"
      @checksum = "{#{@checksum_type}}" + send("#{@checksum_type}_file", real_path).to_s
    when "directory" # Always just timestamp the directory.
      @checksum_type = "ctime"
      @checksum = "{#{@checksum_type}}" + send("#{@checksum_type}_file", path).to_s
    when "link"
      @destination = Puppet::FileSystem.readlink(real_path)
      @checksum = begin
        "{#{@checksum_type}}" + send("#{@checksum_type}_file", real_path).to_s
      rescue
        nil
      end
    when "fifo", "socket"
      @checksum_type = "none"
      @checksum = "{#{@checksum_type}}" + send("#{@checksum_type}_file", real_path).to_s
    else
      raise ArgumentError, _("Cannot manage files of type %{file_type}") % { file_type: stat.ftype }
    end
  end

  def initialize(path, data = {})
    @owner       = data.delete('owner')
    @group       = data.delete('group')
    @mode        = data.delete('mode')
    checksum = data.delete('checksum')
    if checksum
      @checksum_type = checksum['type']
      @checksum      = checksum['value']
    end
    @checksum_type ||= Puppet[:digest_algorithm]
    @ftype       = data.delete('type')
    @destination = data.delete('destination')
    @source      = data.delete('source')
    @content_uri = data.delete('content_uri')

View on GitHub (pinned to e227c27540)

Solutions

1. Exclude device files from the recursion with the `ignore` parameter or by narrowing the served path
2. Do not serve or manage /dev or other pseudo-filesystems with file resources
3. If a specific special file must exist, declare it explicitly (ensure => present with mode/owner) instead of copying it via source

Example fix

# before
file { '/opt/app/dev':
  ensure  => directory,
  source  => 'puppet:///modules/app/dev', # contains device nodes
  recurse => true,
}

# after
file { '/opt/app/dev':
  ensure  => directory,
  source  => 'puppet:///modules/app/dev',
  recurse => true,
  ignore  => ['tty*', 'sd*'],
}

MANAGEABLE_FTYPES = %w[file directory link fifo socket].freeze

def metadata_safe?(path)
  MANAGEABLE_FTYPES.include?(File.stat(path).ftype)
end

def puppet_manageable_file?(path)
  return false unless Puppet::FileSystem.exist?(path)
  MANAGEABLE_FTYPES.include?(Puppet::FileSystem.stat(path).ftype)
end

begin
  Puppet::FileServing::Metadata.new(path)
rescue ArgumentError => e
  raise unless e.message.start_with?('Cannot manage files of type')
  skip path # device/special file: log and continue the walk
end

When it happens

Trigger: Requesting metadata (or a file resource with `source =>` pointing into a directory containing device nodes such as /dev/null-style files); serving a mount whose path includes /dev or another pseudo-filesystem with special files; `puppet file bucket`/file_serving indirection hitting a device file.

Common situations: Recursive file resources pointed at directories that contain Unix device nodes or exotic FIFO/socket-adjacent entries; accidentally using an absolute source path that reaches into /dev; chroot/container images with device files in unexpected places.

Related errors

• Could not find a valid module at %{path}
• Invalid entry at %{error_location}: '%{file_text}'
• %{mount} is already mounted at %{name} at %{error_location}
• Fileset paths must be fully qualified: %{path}
• Fileset paths must exist

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