puppetlabs/puppet · error · ArgumentError

Paths must be fully qualified

Error message

Paths must be fully qualified

What it means

Puppet::FileServing::Base#path= stores a file-serving object's base path and requires it to be absolute, checked with Puppet::FileServing::Base.absolute? (POSIX leading-slash, or drive/UNC form when running on Windows). Any relative path raises ArgumentError. This setter underpins fileserver.conf mounts and metadata construction, so mount points and similar inputs must be absolute.

Source

Thrown at lib/puppet/file_serving/base.rb:62

  end

  # Determine how we deal with links.
  attr_reader :links

  def links=(value)
    value = value.to_sym
    value = :manage if value == :ignore
    # TRANSLATORS ':link', ':manage', ':follow' should not be translated
    raise(ArgumentError, _(":links can only be set to :manage or :follow")) unless [:manage, :follow].include?(value)

    @links = value
  end

  # Set our base path.
  attr_reader :path

  def path=(path)
    raise ArgumentError, _("Paths must be fully qualified") unless Puppet::FileServing::Base.absolute?(path)

    @path = path
  end

  # Set a relative path; this is used for recursion, and sets
  # the file's path relative to the initial recursion point.
  attr_reader :relative_path

  def relative_path=(path)
    raise ArgumentError, _("Relative paths must not be fully qualified") if Puppet::FileServing::Base.absolute?(path)

    @relative_path = path
  end

  # Stat our file, using the appropriate link-sensitive method.
  def stat
    @stat_method ||= links == :manage ? :lstat : :stat
    Puppet::FileSystem.send(@stat_method, full_path)

View on GitHub (pinned to e227c27540)

Solutions

1. Use an absolute path in the mount: `path = /etc/puppetlabs/code/environments/$environment/files/extra`
2. On Windows use drive-letter (C:\...) or UNC (\\server\share\...) absolute paths
3. When building paths in Ruby, anchor them: File.expand_path(p) or root.join(p)

Example fix

# fileserver.conf — before
[extra_files]
  path files/extra
# after
[extra_files]
  path /etc/puppetlabs/code/environments/$environment/files/extra

def mount_path_ok?(p)
  Puppet::Util.absolute_path?(p, :posix) || (Puppet::Util::Platform.windows? && Puppet::Util.absolute_path?(p, :windows))
end
raise ArgumentError, "mount path must be absolute: #{p}" unless mount_path_ok?(p)

def absolute_mount?(p)
  p.is_a?(String) && p.start_with?('/') || p.match?(/\A[a-zA-Z]:[\\\/]/) || p.start_with?('\\\\')
end

When it happens

Trigger: A fileserver.conf mount whose path is relative (`[extra_files]` + `path files/extra`); Ruby code assigning a relative path to a FileServing object; interpolating a relative setting value into path=.

Common situations: Assuming paths resolve relative to puppet.conf or the environment directory; configs ported from tools where relative paths were allowed.

Related errors

• Invalid argument '%{var}' at %{error_location}
• Relative paths must not be fully qualified
• Could not find a valid module at %{path}
• Diff is not supported on this platform
• Fileset paths must be fully qualified: %{path}

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