arsduo/koala · error · Koala::Facebook::AuthenticationError

Batch operations require an access token, none provided.

Error message

Batch operations require an access token, none provided.

What it means

Koala::Facebook::BatchOperation raises Koala::Facebook::AuthenticationError in its constructor when the operation carries no access token (lib/koala/api/batch_operation.rb:29). Facebook's batch endpoint executes every bundled operation on behalf of an authenticated user or app, so Koala refuses to build a tokenless batch operation instead of sending a request guaranteed to fail. Like all pre-call guards, the error is created with nil http_status (see the comment in lib/koala/errors.rb:13-14) — no request ever reached Facebook.

Source

Thrown at lib/koala/api/batch_operation.rb:29

        @identifier = 0

        def self.next_identifier
          @identifier += 1
        end

        def initialize(options = {})
          @identifier = self.class.next_identifier
          @args = (options[:args] || {}).dup # because we modify it below
          @access_token = options[:access_token]
          @http_options = (options[:http_options] || {}).dup # dup because we modify it below
          @batch_args = @http_options.delete(:batch_args) || {}
          @url = options[:url]
          @method = options[:method].to_sym
          @post_processing = options[:post_processing]

          process_binary_args

          raise AuthenticationError.new(nil, nil, "Batch operations require an access token, none provided.") unless @access_token
        end

        def to_batch_params(main_access_token, app_secret)
          # set up the arguments
          if @access_token != main_access_token
            @args[:access_token] = @access_token
            if app_secret
              @args[:appsecret_proof] = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), app_secret, @access_token)
            end
          end
          args_string = Koala.http_service.encode_params(@args)

          response = {
            :method => @method.to_s,
            :relative_url => @url,
          }

          # handle batch-level arguments, such as name, depends_on, and attached_files

View on GitHub (pinned to 47d052063e)

Solutions

1. Construct the API with a token before batching: Koala::Facebook::API.new(access_token) — api.batch operations inherit it
2. If the token comes from OAuth, complete and verify the exchange (@oauth.get_access_token(code)) and fail loudly if it returns nil
3. Check that the token env var / credentials are actually loaded in the environment that runs the batch job
4. Wrap batch calls in rescue Koala::Facebook::AuthenticationError to route the user back through re-authorization

Example fix

# before
api = Koala::Facebook::API.new # no access token
results = api.batch do |batch_api|
  batch_api.get_object('me') # raises AuthenticationError while building the batch
end

# after
api = Koala::Facebook::API.new(ENV.fetch('FACEBOOK_ACCESS_TOKEN'))
results = api.batch do |batch_api|
  batch_api.get_object('me')
  batch_api.get_connections('me', 'friends')
end

def batchable?(api)
  !api.access_token.to_s.empty?
end

raise 'API needs an access token for batch requests' unless batchable?(api)
api.batch { |batch_api| batch_api.get_object('me') }

begin
  api.batch { |batch_api| batch_api.get_object('me') }
rescue Koala::Facebook::AuthenticationError => e
  # e.http_status is nil: caught client-side, no request was sent
  redirect_to oauth_authorization_path
end

When it happens

Trigger: Calling api.batch { |batch_api| ... } on a Koala::Facebook::API instance constructed without an access token (e.g. Koala::Facebook::API.new with no argument), or building Koala::Facebook::BatchOperation manually with options[:access_token] nil or absent. The raise fires inside initialize, while the operations are being collected, before the batch HTTP request is assembled.

Common situations: Legacy apps that read public data with a tokenless API and later refactor those reads into a batch; the OAuth code-for-token exchange failing silently so nil is passed to API.new; batch code paths that only run in production where ENV['FACEBOOK_ACCESS_TOKEN'] is unset; test suites that stub single calls but never exercise api.batch.

Related errors

• Delete requires an access token
• Write operations require an access token
• Unliking requires an access token
• Koala::Facebook::ServerError.new(result.status.to_i, result.
• type must be includedin args when searching

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