jnunemaker/httparty · error · HTTParty::UnsupportedFormat

'#{format.inspect}' Must be one of: #{supported_format_names

Error message

'#{format.inspect}' Must be one of: #{supported_format_names}

What it means

HTTParty raises UnsupportedFormat when the format set via `format :xyz` is not one of the formats the configured parser supports. validate_format runs when the format DSL is used: it checks parser.supports_format?(format) when the parser responds to that class method, and lists the supported names in the message. The default parser supports the formats mapped in HTTParty::Parser::SupportedFormats (json, xml, html, plain, csv, atom, rss and related mime-mapped names).

Source

Thrown at lib/httparty.rb:633

      unless options.key?(:maintain_method_across_redirects)
        options[:maintain_method_across_redirects] = true
      end
    end

    def perform_request(http_method, path, options, &block) #:nodoc:
      build_request(http_method, path, options).perform(&block)
    end

    def process_cookies(options) #:nodoc:
      return unless options[:cookies] || default_cookies.any?
      options[:headers] ||= headers.dup
      options[:headers]['cookie'] = cookies.merge(options.delete(:cookies) || {}).to_cookie_string
    end

    def validate_format
      if format && parser.respond_to?(:supports_format?) && !parser.supports_format?(format)
        supported_format_names = parser.supported_formats.map(&:to_s).sort.join(', ')
        raise UnsupportedFormat, "'#{format.inspect}' Must be one of: #{supported_format_names}"
      end
    end
  end

  def self.normalize_base_uri(url) #:nodoc:
    normalized_url = url.dup
    use_ssl = (normalized_url =~ /^https/) || (normalized_url =~ /:443\b/)
    ends_with_slash = normalized_url =~ /\/$/

    normalized_url.chop! if ends_with_slash
    normalized_url.gsub!(/^https?:\/\//i, '')

    "http#{'s' if use_ssl}://#{normalized_url}"
  end

  class Basement #:nodoc:
    include HTTParty
  end

View on GitHub (pinned to 8f4a09e343)

Solutions

1. Check what is supported: `HTTParty::Parser.supported_formats.inspect` and use one of those symbols.
2. For custom formats, subclass HTTParty::Parser, add to SupportedFormats and define the method, then `parser MyParser` before `format :msgpack`.
3. If the body is a non-standard format, skip `format` entirely and parse response.body manually.

Example fix

# before
class Client
  include HTTParty
  format :msgpack   # UnsupportedFormat
end

# after
require 'msgpack'
class MsgpackParser < HTTParty::Parser
  SupportedFormats.update({ 'application/msgpack' => :msgpack })
  def msgpack
    MessagePack.unpack(body)
  end
end

class Client
  include HTTParty
  parser MsgpackParser
  format :msgpack
end

fmt = :msgpack
unless (parser_class || HTTParty::Parser).supports_format?(fmt)
  raise HTTParty::UnsupportedFormat, "#{fmt} not supported by #{parser_class || HTTParty::Parser}"
end

supported = ->(fmt) { HTTParty::Parser.supported_formats.map(&:to_s).include?(fmt.to_s) }

begin
  format fmt
rescue HTTParty::UnsupportedFormat
  parser MyParserWithFmt  # defines the format first
  format fmt
end

When it happens

Trigger: `format :msgpack` or `format :xlsx` with the default parser inside an HTTParty class; also when a custom parser class defines SupportedFormats without including the format later set via `format :json`.

Common situations: Consuming APIs that return MessagePack, protobuf or other non-default content, upgrading httparty and hitting stricter validation, or setting a format symbol that only exists after a custom parser is wired up in the wrong order.

Related errors

• Default params must be an object which responds to #to_hash
• Headers must be an object which responds to #to_hash
• Cookies must be an object which responds to #to_hash
• The URI adapter should respond to #parse
• #{ timeout_type } must be an integer or float

AI-assisted analysis of jnunemaker/httparty@8f4a09e343 (2026-08-21). Data as JSON: /api/errors/c045bb2d1ce27e41. Report an issue: GitHub.