puppetlabs/puppet · error · ArgumentError

Supported values for Property#array_matching are 'first' and

Error message

Supported values for Property#array_matching are 'first' and 'all'

What it means

array_matching is a DSL attribute on custom type properties. It controls how an array should-value is compared: :first (default) matches on the first element, :all requires all elements to be present. The setter interns strings to symbols and rejects anything outside [:first, :all] with ArgumentError at type-definition time - that is, as soon as Puppet loads the type, not when a resource is applied.

Source

Thrown at lib/puppet/property.rb:101

    #
    # @note The semantics of these modes are implemented by the method {#insync?}. That method is the default
    #   implementation and it has a backwards compatible behavior that imposes additional constraints
    #   on what constitutes a positive match. A derived property may override that method.
    # @return [Symbol] (:first) the mode in which matching is performed
    # @see #insync?
    # @dsl type
    # @api public
    #
    def array_matching
      @array_matching ||= :first
    end

    # @comment This is documented as an attribute - see the {array_matching} method.
    #
    def array_matching=(value)
      value = value.intern if value.is_a?(String)
      # TRANSLATORS 'Property#array_matching', 'first', and 'all' should not be translated
      raise ArgumentError, _("Supported values for Property#array_matching are 'first' and 'all'") unless [:first, :all].include?(value)

      @array_matching = value
    end

    # Used to mark a type property as having or lacking idempotency (on purpose
    # generally). This is used to avoid marking the property as a
    # corrective_change when there is known idempotency issues with the property
    # rendering a corrective_change flag as useless.
    # @return [Boolean] true if the property is marked as idempotent
    def idempotent
      @idempotent.nil? ? @idempotent = true : @idempotent
    end

    # Attribute setter for the idempotent attribute.
    # @param [bool] value boolean indicating if the property is idempotent.
    # @see idempotent
    def idempotent=(value)
      @idempotent = value

View on GitHub (pinned to e227c27540)

Solutions

Use :first (or omit it - it is the default) or :all, as a symbol or exact string.
If neither semantic fits, leave array_matching unset and override insync? in the property to implement custom matching.

Example fix

# before (custom type)
newproperty(:members, :array_matching => :any) { ... }   # ArgumentError when the type loads

# after
newproperty(:members, :array_matching => :all) { ... }

Defensive patterns

Strategy: validation

Validate before calling

value = :all
raise ArgumentError, 'bad array_matching' unless [:first, :all].include?(value)
newproperty(:members, :array_matching => value) { ... }

Type guard

def valid_array_matching?(v)
  v = v.to_sym if v.is_a?(String)
  [:first, :all].include?(v)
end

Prevention

The vocabulary is exactly :first and :all - nothing else.
Test that a custom type loads (puppet parser validate or a spec invoking Puppet::Type.type) before shipping.
Prefer symbols over strings for DSL attributes; strings must be exact after interning.

When it happens

Trigger: In a custom type: newproperty(:foo, :array_matching => :any) do ... end, or array_matching 'fist' (typo), or passing nil / a value that cannot be interned.

Common situations: Custom type authors guessing the vocabulary (:any, :match_all, :all_matching); values copied from other frameworks' APIs; near-miss strings that get interned and then fail the whitelist check.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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