puppetlabs/puppet · error · Puppet::Settings::InterpolationError

Error converting value for param '%{name}': %{detail}

Error message

Error converting value for param '%{name}': %{detail}

What it means

On the settings read path, lookup_and_convert calls convert(value, name) to expand a setting's value; if conversion raises Puppet::Settings::InterpolationError, this wrapper re-raises it with the offending parameter's name attached (the inner error has no setting context). The value of :code is passed through unconverted. The underlying cause is nearly always an unresolvable $variable inside a setting value (see the 'Could not find value for' error).

Source

Thrown at lib/puppet/settings.rb:1500

        setting.print(val)
      end
    end

    private

    def lookup_and_convert(name, &block)
      val = lookup(name)
      # if we interpolate code, all hell breaks loose.
      if name == :code
        val
      else
        # Convert it if necessary
        begin
          val = convert(val, name)
        rescue InterpolationError => err
          # This happens because we don't have access to the param name when the
          # exception is originally raised, but we want it in the message
          raise InterpolationError, _("Error converting value for param '%{name}': %{detail}") % { name: name, detail: err }, err.backtrace
        end

        yield val
      end
    end

    def convert(value, setting_name)
      case value
      when nil
        nil
      when String
        failed_environment_interpolation = false
        interpolated_value = value.gsub(/\$(\w+)|\$\{(\w+)\}/) do |expression|
          varname = ::Regexp.last_match(2) || ::Regexp.last_match(1)
          interpolated_expression =
            if varname != ENVIRONMENT_SETTING || ok_to_interpolate_environment(setting_name)
              if varname == ENVIRONMENT_SETTING && @environment
                @environment

View on GitHub (pinned to e227c27540)

Solutions

1. Take the param name from the message, locate that setting in puppet.conf (all sections plus CLI overrides), and inspect its value for $ references.
2. Fix the referenced name to a real setting, or declare the missing setting so interpolation can resolve it.
3. If the $ is literal data rather than a reference, move the value out of settings or split it so no $name token appears.

Example fix

# before (puppet.conf)
[main]
certdir = $ssldirf/certs   # typo: no setting named ssldirf

# after
[main]
certdir = $ssldir/certs

# pre-resolve every $var token in a setting value before Puppet reads it
value.scan(/\$(?:\{(\w+)\}|(\w+))/).flatten.compact.each do |name|
  next if %w[environment run_mode].include?(name)
  raise Puppet::Error, "unresolvable $#{name} in setting value" if Puppet.settings.setting(name.to_sym).nil?
end

begin
  Puppet.settings[:mysetting]
rescue Puppet::Settings::InterpolationError => e
  Puppet.err("#{e.message} — fix the $variable in the named setting's value")
  raise
end

When it happens

Trigger: Reading Puppet.settings[:some_setting] (or any code path that resolves settings) where the value or its default contains $var/${var} and var is not a defined setting, run_mode, or environment; CLI overrides injecting strings with $ into a setting value.

Common situations: Typo'd variable references in puppet.conf discovered only at runtime; settings referencing variables removed in a Puppet upgrade; templated puppet.conf deployed with unresolved placeholders.

Related errors

• Could not find value for %{expression}
• Global option %{option} does not exist in Puppet.settings
• Cannot use empty string as a class name
• Recursive lookup detected in [%{name_stack}]
• Invalid run mode '#{mode}'

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