puppetlabs/puppet · error · ArgumentError

Invalid mount name format '%{name}'

Error message

Invalid mount name format '%{name}'

What it means

Puppet::FileServing::Mount#initialize validates the mount name against /^[-\w]+$/ (letters, digits, underscore, hyphen only). The name becomes the first path component of puppet:///<mount>/... URIs, so slashes, dots, spaces, or other characters break URI routing and are rejected immediately.

Source

Thrown at lib/puppet/file_serving/mount.rb:22

require_relative '../../puppet/file_serving'
require_relative '../../puppet/file_serving/metadata'
require_relative '../../puppet/file_serving/content'

# Broker access to the filesystem, converting local URIs into metadata
# or content objects.
class Puppet::FileServing::Mount
  include Puppet::Util::Logging

  attr_reader :name

  def find(path, options)
    raise NotImplementedError
  end

  # Create our object.  It must have a name.
  def initialize(name)
    unless name =~ /^[-\w]+$/
      raise ArgumentError, _("Invalid mount name format '%{name}'") % { name: name }
    end

    @name = name

    super()
  end

  def search(path, options)
    raise NotImplementedError
  end

  def to_s
    "mount[#{@name}]"
  end

  # A noop.
  def validate
  end

View on GitHub (pinned to e227c27540)

Solutions

1. Rename the mount to use only [A-Za-z0-9_-], e.g. `[my_data]` or `[my-data]`
2. Update any `puppet:///<mount>/...` source URIs that referenced the old name
3. If generating configs programmatically, sanitize names with `name.gsub(/[^-\w]/, '_')` before writing the header

Example fix

# before (fileserver.conf)
[app.data]
  path /srv/app/data

# after
[app_data]
  path /srv/app/data

MOUNT_NAME = /\A[-\w]+\z/

def valid_mount_name?(name)
  name.is_a?(String) && name.match?(MOUNT_NAME)
end

def mount_header(line)
  m = line.match(/\A\s*\[([-\w]+)\]\s*\z/)
  m && m[1]
end

begin
  mount = Puppet::FileServing::Mount::File.new(name)
rescue ArgumentError => e
  raise unless e.message.start_with?('Invalid mount name format')
  name = name.gsub(/[^-\w]/, '_')
  retry
end

When it happens

Trigger: A fileserver.conf section header like `[my.mount]`, `[my modules]`, `[a/b]`, or an empty-ish header; the same validation applies wherever a Mount subclass is instantiated programmatically.

Common situations: Naming mounts after dotted hostnames or domain paths; pasting section headers with trailing whitespace or smart quotes; scripts that generate fileserver.conf from arbitrary directory names.

Related errors

• Mounts without paths are not usable
• %{path} does not exist or is not a directory
• %{path} is not readable
• Invalid entry at %{error_location}: '%{file_text}'
• %{mount} is already mounted at %{name} at %{error_location}

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