puppetlabs/puppet · error · ArgumentError

User provider %{name} can not manage home directories

Error message

User provider %{name} can not manage home directories

What it means

Raised by the validate block of the `managehome` property on the `user` type when managehome is truthy (after munge) and the selected provider exists but does not declare the `manages_homedir` feature (provider.class.manages_homedir? is false). Providers with the feature include useradd, pw, aix, openbsd, hpux, windows_adsi, and user_role_add; the LDAP provider and macOS directoryservice provider do not declare it, so they cannot create/remove home directories (on Windows the 'home' is the user profile).

Source

Thrown at lib/puppet/type/user.rb:443

    newparam(:managehome, :boolean => true, :parent => Puppet::Parameter::Boolean) do
      desc "Whether to manage the home directory when Puppet creates or removes the user.
        This creates the home directory if Puppet also creates the user account, and deletes the
        home directory if Puppet also removes the user account.

        This parameter has no effect unless Puppet is also creating or removing the user in the
        resource at the same time. For instance, Puppet creates a home directory for a managed
        user if `ensure => present` and the user does not exist at the time of the Puppet run.
        If the home directory is then deleted manually, Puppet will not recreate it on the next
        run.

        Note that on Windows, this manages creation/deletion of the user profile instead of the
        home directory. The user profile is stored in the `C:\\Users\\<username>` directory."

      defaultto false

      validate do |val|
        if munge(val)
          raise ArgumentError, _("User provider %{name} can not manage home directories") % { name: provider.class.name } if provider and !provider.class.manages_homedir?
        end
      end
    end

    newproperty(:expiry, :required_features => :manages_expiry) do
      desc "The expiry date for this user. Provide as either the special
           value `absent` to ensure that the account never expires, or as
           a zero-padded YYYY-MM-DD format -- for example, 2010-02-19."

      newvalues :absent
      newvalues(/^\d{4}-\d{2}-\d{2}$/)

      validate do |value|
        if value.intern != :absent and value !~ /^\d{4}-\d{2}-\d{2}$/
          # TRANSLATORS YYYY-MM-DD represents a date with a four-digit year, a two-digit month, and a two-digit day,
          # TRANSLATORS separated by dashes.
          raise ArgumentError, _("Expiry dates must be YYYY-MM-DD or the string \"absent\"")
        end

View on GitHub (pinned to e227c27540)

Solutions

1. Set `managehome => false` (the default) on nodes whose provider lacks the feature
2. Manage the home directory explicitly with a `file { '/home/alice': ensure => directory, ... }` resource plus appropriate ownership
3. If LDAP is only incidental, choose a local provider that has the feature (e.g. useradd) for those nodes
4. Gate the attribute per platform in the profile: only set managehome when the provider supports it

Example fix

# before
user { 'alice':
  ensure      => present,
  managehome => true,   # fails under directoryservice/ldap providers
}

# after
user { 'alice':
  ensure => present,
}
file { '/home/alice':
  ensure => directory,
  owner  => 'alice',
  group  => 'alice',
  mode   => '0700',
}

# Ruby API: check the feature before enabling managehome
res = Puppet::Type.type(:user).new(name: 'alice', ensure: :present)
provider = Puppet::Type.type(:user).provider(res[:provider]) rescue nil
managehome_ok = provider && provider.manages_homes?

# Puppet DSL: gate on platform in the profile
if $facts['os']['name'] != 'Darwin' {
  User { managehome => true }
}

begin
  Puppet::Type.type(:user).new(name: 'alice', ensure: :present, managehome: true)
rescue Puppet::Error => e
  # provider feature check failure surfaces during resource creation
  fallback = Puppet::Type.type(:user).new(name: 'alice', ensure: :present, managehome: false)
end

When it happens

Trigger: `user { 'alice': ensure => present, managehome => true }` on a node where the provider resolves to directoryservice (macOS) or ldap; forcing managehome on a node whose provider selection changed after an OS upgrade.

Common situations: Shared profile classes that set managehome => true applied to macOS laptops or LDAP-managed hosts; migrating from useradd-managed Linux nodes to a directory service; Puppet runs failing at resource compilation, not at sync time.

Related errors

• Password warning days must be provided as a number.
• Group names must be provided, not GID numbers.
• Group names must be provided as an array, not a comma-separa
• Group names must not be empty. If you want to specify "no gr
• Expiry dates must be YYYY-MM-DD or the string "absent"

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