puppetlabs/puppet · critical · Puppet::Error

Cannot determine basic system flavour

Error message

Cannot determine basic system flavour

What it means

lib/puppet/feature/base.rb executes when Puppet is required: it registers platform features, then raises Puppet::Error unless the `posix` feature (the etc extension loads, Etc.getpwuid(0) is non-nil, and the syslog library is present) or the `microsoft_windows` feature is true. In other words, Puppet cannot identify the OS flavour as POSIX or Windows, so nothing else can safely load.

Source

Thrown at lib/puppet/feature/base.rb:21

require_relative '../../puppet/util/feature'

# Add the simple features, all in one file.

# Order is important as some features depend on others

# We have a syslog implementation
Puppet.features.add(:syslog, :libs => ["syslog"])

# We can use POSIX user functions
Puppet.features.add(:posix) do
  require 'etc'
  !Etc.getpwuid(0).nil? && Puppet.features.syslog?
end

# We can use Microsoft Windows functions
Puppet.features.add(:microsoft_windows) { Puppet::Util::Platform.windows? }

raise Puppet::Error, _("Cannot determine basic system flavour") unless Puppet.features.posix? or Puppet.features.microsoft_windows?

# We've got LDAP available.
Puppet.features.add(:ldap, :libs => ["ldap"])

# We have the Rdoc::Usage library.
Puppet.features.add(:usage, :libs => %w[rdoc/ri/ri_paths rdoc/usage])

# We have libshadow, useful for managing passwords.
Puppet.features.add(:libshadow, :libs => ["shadow"])

# We're running as root.
Puppet.features.add(:root) do
  require_relative '../../puppet/util/suidmanager'
  Puppet::Util::SUIDManager.root?
end

# We have lcs diff
Puppet.features.add :diff, :libs => %w[diff/lcs diff/lcs/hunk]

View on GitHub (pinned to e227c27540)

Solutions

1. Ensure /etc/passwd exists and contains a root entry in the environment where Puppet runs
2. Use a full Ruby build that ships the etc and syslog extensions — verify with `ruby -e "require 'etc'; require 'syslog'; p Etc.getpwuid(0)"`
3. Run Puppet on a supported POSIX platform or on Windows instead of a stripped image

Example fix

# before: distroless image with no /etc/passwd
FROM scratch ...
# after: base image with a passwd database
FROM ubuntu:24.04
RUN ruby -e "require 'etc'; p Etc.getpwuid(0)" # => #<Struct ... uid=0>

posix_flavour = begin
  require 'etc'
  require 'syslog'
  !Etc.getpwuid(0).nil?
rescue LoadError
  false
end
supported = posix_flavour || (defined?(Puppet::Util::Platform) && Puppet::Util::Platform.windows?) || Gem.win_platform?
abort 'puppet unsupported on this platform/runtime' unless supported
require 'puppet'

When it happens

Trigger: Requiring puppet on a platform that fails the POSIX probe: minimal containers or chroots without a root entry in /etc/passwd (Etc.getpwuid(0) returns nil); a Ruby build compiled without the etc or syslog stdlib extensions; genuinely unsupported operating systems.

Common situations: Distroless/minimal Docker images with a scrubbed /etc/passwd; embedded or custom Ruby builds; running Puppet-based tooling under an unusual runtime (e.g. stripped JRuby install).

Related errors

• Diff is not supported on this platform
• RegisterEventSourceW failed to open Windows eventlog
• ReportEventW failed to report event to Windows eventlog
• Operation not permitted
• Is a directory: %{directory}

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