{"record":{"id":"2e7045bb40e16db4","repo":"puppetlabs/puppet","slug":"cannot-determine-basic-system-flavour","errorCode":null,"errorMessage":"Cannot determine basic system flavour","messagePattern":"Cannot determine basic system flavour","errorType":"exception","errorClass":"Puppet::Error","httpStatus":null,"severity":"critical","filePath":"lib/puppet/feature/base.rb","lineNumber":21,"sourceCode":"require_relative '../../puppet/util/feature'\n\n# Add the simple features, all in one file.\n\n# Order is important as some features depend on others\n\n# We have a syslog implementation\nPuppet.features.add(:syslog, :libs => [\"syslog\"])\n\n# We can use POSIX user functions\nPuppet.features.add(:posix) do\n  require 'etc'\n  !Etc.getpwuid(0).nil? && Puppet.features.syslog?\nend\n\n# We can use Microsoft Windows functions\nPuppet.features.add(:microsoft_windows) { Puppet::Util::Platform.windows? }\n\nraise Puppet::Error, _(\"Cannot determine basic system flavour\") unless Puppet.features.posix? or Puppet.features.microsoft_windows?\n\n# We've got LDAP available.\nPuppet.features.add(:ldap, :libs => [\"ldap\"])\n\n# We have the Rdoc::Usage library.\nPuppet.features.add(:usage, :libs => %w[rdoc/ri/ri_paths rdoc/usage])\n\n# We have libshadow, useful for managing passwords.\nPuppet.features.add(:libshadow, :libs => [\"shadow\"])\n\n# We're running as root.\nPuppet.features.add(:root) do\n  require_relative '../../puppet/util/suidmanager'\n  Puppet::Util::SUIDManager.root?\nend\n\n# We have lcs diff\nPuppet.features.add :diff, :libs => %w[diff/lcs diff/lcs/hunk]","sourceCodeStart":3,"sourceCodeEnd":39,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/feature/base.rb#L3-L39","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Ensure /etc/passwd exists and contains a root entry in the environment where Puppet runs","Use a full Ruby build that ships the etc and syslog extensions — verify with `ruby -e \"require 'etc'; require 'syslog'; p Etc.getpwuid(0)\"`","Run Puppet on a supported POSIX platform or on Windows instead of a stripped image"],"exampleFix":"# before: distroless image with no /etc/passwd\nFROM scratch ...\n# after: base image with a passwd database\nFROM ubuntu:24.04\nRUN ruby -e \"require 'etc'; p Etc.getpwuid(0)\" # => #<Struct ... uid=0>","handlingStrategy":"validation","validationCode":"posix_flavour = begin\n  require 'etc'\n  require 'syslog'\n  !Etc.getpwuid(0).nil?\nrescue LoadError\n  false\nend\nsupported = posix_flavour || (defined?(Puppet::Util::Platform) && Puppet::Util::Platform.windows?) || Gem.win_platform?\nabort 'puppet unsupported on this platform/runtime' unless supported\nrequire 'puppet'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Smoke-test images with `ruby -e \"require 'etc'; p Etc.getpwuid(0)\"` before installing Puppet","Keep /etc/passwd (with a root entry) in minimal containers; use full Ruby builds that include etc/syslog"],"tags":["puppet","platform","posix","windows","boot","runtime-environment"],"backgroundTag":"unsupported-platform","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}