arsduo/koala · error · ArgumentError

type must be includedin args when searching

Error message

type must be includedin args when searching

What it means

search raises ArgumentError ('type must be includedin args when searching' — the 'includedin' typo is verbatim in lib/koala/api/graph_api_methods.rb:354) when the args hash contains neither :type nor 'type'. The source comment explains why: Koala normally does not police Facebook's parameters, but the search endpoint fails with cryptic server-side errors when type is missing, so this convenience method validates it up front. Both symbol and string keys satisfy the guard.

Source

Thrown at lib/koala/api/graph_api_methods.rb:354

      def delete_like(id, options = {}, &block)
        # Unlikes a given object for the logged-in user
        raise AuthenticationError.new(nil, nil, "Unliking requires an access token") unless access_token
        graph_call("#{id}/likes", {}, "delete", options, &block)
      end

      # Search for a given query among visible Facebook objects.
      # See {http://developers.facebook.com/docs/reference/api/#searching Facebook documentation} for more information.
      #
      # @param search_terms the query to search for
      # @param args object type and any additional arguments, such as fields, etc.
      # @param options (see #get_object)
      # @param block (see Koala::Facebook::API#api)
      #
      # @return [Koala::Facebook::API::GraphCollection] an array of search results
      def search(search_terms, args = {}, options = {}, &block)
        # Normally we wouldn't enforce Facebook API behavior, but the API fails with cryptic error
        # messages if you fail to include a type term. For a convenience method, that is valuable.
        raise ArgumentError, "type must be includedin args when searching" unless args[:type] || args["type"]
        graph_call("search", args.merge("q" => search_terms), "get", options, &block)
      end

      # Convenience Methods
      # In general, we're trying to avoid adding convenience methods to Koala
      # except to support cases where the Facebook API requires non-standard input
      # such as JSON-encoding arguments, posts directly to objects, etc.

      # Get a page's access token, allowing you to act as the page.
      # Convenience method for @api.get_object(page_id, :fields => "access_token").
      #
      # @param id the page ID
      # @param args (see #get_object)
      # @param options (see #get_object)
      # @param block (see Koala::Facebook::API#api)
      #
      # @return the page's access token (discarding expiration and any other information)
      def get_page_access_token(id, args = {}, options = {}, &block)

View on GitHub (pinned to 47d052063e)

Solutions

1. Pass the type in args: api.search('chocolate', type: 'page')
2. If you put type into options (the third argument), move it into args (the second) — the signature is search(search_terms, args = {}, options = {}, &block)
3. Whitelist types at your input boundary (user, page, event, group, place, post) so missing or invalid values fail before hitting Facebook
4. When migrating old code, grep for search( calls and add the type explicitly rather than relying on Facebook defaults

Example fix

# before
api.search('koala gem') # => ArgumentError: type must be includedin args when searching

# after
api.search('koala gem', type: 'post', fields: 'message,from')
api.search('blue bottle', 'type' => 'place', 'center' => '37.77,-122.41', 'distance' => 1000)

SEARCH_TYPES = %w[user page event group place post].freeze

def safe_search(api, terms, args)
  type = args[:type] || args['type']
  raise ArgumentError, "args[:type] must be one of #{SEARCH_TYPES.join(', ')}" unless SEARCH_TYPES.include?(type)
  api.search(terms, args)
end

begin
  api.search(terms, args)
rescue ArgumentError => e
  # local validation failure — surface to the caller, do not retry
  render json: {error: e.message}, status: 400
end

When it happens

Trigger: api.search('chocolate') or api.search('chocolate', limit: 10) — any call whose args omit type. Fixed by api.search('chocolate', type: 'page') with one of the documented types: post, user, page, event, group, place.

Common situations: Porting from old examples that show only the search terms; passing type under a different key (object_type:) or accidentally in the options hash (third parameter) instead of args (second); dynamic arg builders that drop blank values and remove type when a form field is empty.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• Wrong number of arguments for put_#{method == "photos" ? "pi
• Koala::Facebook::ServerError.new(result.status.to_i, result.
• Batch operations require an access token, none provided.
• Delete requires an access token
• Write operations require an access token

AI-assisted analysis of arsduo/koala@47d052063e (2026-08-23). Data as JSON: /api/errors/f8107b6199416dce. Report an issue: GitHub.