puppetlabs/puppet · error · Puppet::Error

FormatMessageW could not format code %{code}

Error message

FormatMessageW could not format code %{code}

What it means

Puppet::Util::Windows::Error.format_error_code raises this plain Puppet::Error when the Win32 FormatMessageW call itself fails while rendering a Windows error code to text — typically because the code is not a system message id or the message table/language resource is unavailable. The raise deliberately uses Puppet::Error (not Windows::Error) to avoid infinite recursion when formatting the failure of formatting.

Source

Thrown at lib/puppet/util/windows/error.rb:45

    # 3.User default LANGID, based on the user's default locale value
    # 4.System default LANGID, based on the system default locale value
    # 5.US English
    dwLanguageId = 0
    flags = FORMAT_MESSAGE_ALLOCATE_BUFFER |
            FORMAT_MESSAGE_FROM_SYSTEM |
            FORMAT_MESSAGE_ARGUMENT_ARRAY |
            FORMAT_MESSAGE_IGNORE_INSERTS |
            FORMAT_MESSAGE_MAX_WIDTH_MASK
    error_string = ''.dup

    # this pointer actually points to a :lpwstr (pointer) since we're letting Windows allocate for us
    FFI::MemoryPointer.new(:pointer, 1) do |buffer_ptr|
      length = FormatMessageW(flags, FFI::Pointer::NULL, code, dwLanguageId,
                              buffer_ptr, 0, FFI::Pointer::NULL)

      if length == FFI::WIN32_FALSE
        # can't raise same error type here or potentially recurse infinitely
        raise Puppet::Error, _("FormatMessageW could not format code %{code}") % { code: code }
      end

      # returns an FFI::Pointer with autorelease set to false, which is what we want
      buffer_ptr.read_win32_local_pointer do |wide_string_ptr|
        if wide_string_ptr.null?
          raise Puppet::Error, _("FormatMessageW failed to allocate buffer for code %{code}") % { code: code }
        end

        error_string = wide_string_ptr.read_wide_string(length)
      end
    end

    error_string
  end

  ERROR_FILE_NOT_FOUND      = 2
  ERROR_ACCESS_DENIED       = 5

View on GitHub (pinned to e227c27540)

Solutions

1. Validate that the code is a genuine Win32/HRESULT value before formatting; otherwise print it numerically.
2. Report upstream if a legitimate system code fails to format — the message table may be missing on that install.

Example fix

# before
raise Puppet::Util::Windows::Error.new('request failed', arbitrary_code)

# after - keep a numeric fallback for codes you don't control
begin
  raise Puppet::Util::Windows::Error.new('request failed', arbitrary_code)
rescue Puppet::Error
  raise "request failed (Windows code 0x#{arbitrary_code.to_s(16).upcase})"
end

def safe_win32_message(code)
  Puppet::Util::Windows::Error.format_error_code(code)
rescue Puppet::Error
  "unformatted Windows error 0x#{code.to_s(16).upcase}"
end

When it happens

Trigger: Constructing Puppet::Util::Windows::Error.new(msg, code) — which always calls format_error_code — with a bogus or non-Win32 code (e.g. an FFI wrapper returning a custom HRESULT from a message table Puppet cannot reach), during error handling on Windows.

Common situations: Passing arbitrary integer return codes from FFI bindings into Puppet's error class; secondary noise that obscures the original failure being reported.

Related errors

• Failed to get computer name
• Failed to get user name
• FormatMessageW failed to allocate buffer for code %{code}
• RegisterEventSourceW failed to open Windows eventlog
• ReportEventW failed to report event to Windows eventlog

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