puppetlabs/puppet · error · ArgumentError

Path must start with a slash

Error message

Path must start with a slash

What it means

Every fileserver service method (get_file_metadata, get_file_content, get_file_skeleton) routes through validate_path, which requires the module-relative path to match PATH_REGEX (%r{^/}). The path must begin with a literal slash, e.g. /modules/mymod/files/config.conf; a path like modules/foo or a full puppet:/// URL is rejected with ArgumentError.

Source

Thrown at lib/puppet/http/service/file_server.rb:198

      params: {
        environment: environment,
        code_id: code_id,
      }
    ) do |res|
      if res.success?
        res.read_body(&block)
      end
    end

    process_response(response)

    response
  end

  private

  def validate_path(path)
    raise ArgumentError, "Path must start with a slash" unless path =~ PATH_REGEX
  end
end

View on GitHub (pinned to e227c27540)

Solutions

1. Prepend '/' when missing: path = "/#{path}" unless path.start_with?('/')
2. Convert puppet:/// URLs first: strip the scheme/host with Puppet::Util.uri_split (or a regex) and use the path portion
3. Centralize path construction in one helper that asserts the leading slash

Example fix

# before (ruby)
api.get_file_content('modules/apache2/files/httpd.conf') # => ArgumentError

# after
api.get_file_content('/modules/apache2/files/httpd.conf')

# ruby
def normalized_path(path)
  path = path.sub(%r{\Apuppet://[^/]*/}, '') if path.start_with?('puppet:')
  path.start_with?('/') ? path : "/#{path}"
end
path = normalized_path(path)
api.get_file_content(path)

def valid_fileserver_path?(p)
  p.is_a?(String) && p.start_with?('/')
end

begin
  api.get_file_content(path)
rescue ArgumentError => e
  raise unless e.message.include?('slash')
  api.get_file_content("/#{path}")
end

When it happens

Trigger: Calling api.get_file_content('modules/apache2/files/httpd.conf') without the leading slash; passing a puppet:///modules/... source URL where a path is expected.

Common situations: Reusing a Puppet source URI (puppet:///modules/...) as the path instead of stripping scheme and host; paths built by concatenation where the leading slash was dropped; code ported from the old file_metadata indirector that accepted slightly different formats.

Related errors

• %{path} does not exist or is not a directory
• puppet.tasks/unparseable-metadata
• Could not find a valid module at %{path}
• Paths must be fully qualified
• Relative paths must not be fully qualified

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