arsduo/koala · error · ArgumentError

Initialize must receive a hash with :app_id and either :app_

Error message

Initialize must receive a hash with :app_id and either :app_access_token or :secret! (received #{options.inspect})

What it means

Koala::Facebook::RealtimeUpdates#initialize needs an application ID plus either an app access token or the app secret, checking the options hash first and then the global Koala.config fallback for all three. If after those fallbacks the app_id is missing, or both the token and the secret are missing, it raises ArgumentError with options.inspect embedded in the message, because every later operation (subscribe, unsubscribe, list_subscriptions) requires app-level authentication.

Source

Thrown at lib/koala/realtime_updates.rb:27

      attr_reader :app_id, :app_access_token, :secret

      # Create a new RealtimeUpdates instance.
      # If you don't have your app's access token, provide the app's secret and
      # Koala will make a request to Facebook for the appropriate token.
      #
      # @param options initialization options.
      # @option options :app_id the application's ID.
      # @option options :app_access_token an application access token, if known.
      # @option options :secret the application's secret.
      #
      # @raise ArgumentError if the application ID and one of the app access token or the secret are not provided.
      def initialize(options = {})
        @app_id = options[:app_id] || Koala.config.app_id
        @app_access_token = options[:app_access_token] || Koala.config.app_access_token
        @secret = options[:secret] || Koala.config.app_secret
        unless @app_id && (@app_access_token || @secret) # make sure we have what we need
          raise ArgumentError, "Initialize must receive a hash with :app_id and either :app_access_token or :secret! (received #{options.inspect})"
        end
      end

      # The app access token, either provided on initialization or fetched from Facebook using the
      # app_id and secret.
      def app_access_token
        # If a token isn't provided but we need it, fetch it
        @app_access_token ||= Koala::Facebook::OAuth.new(@app_id, @secret).get_app_access_token
      end

      # The application API interface used to communicate with Facebook.
      # @return [Koala::Facebook::API]
      def api
        # Only instantiate the API if needed. validate_update doesn't require it, so we shouldn't
        # make an unnecessary request to get the app_access_token.
        @api ||= API.new(app_access_token)
      end

View on GitHub (pinned to 47d052063e)

Solutions

1. Pass credentials explicitly: RealtimeUpdates.new(app_id: ENV["FACEBOOK_APP_ID"], secret: ENV["FACEBOOK_APP_SECRET"]).
2. Or set the globals once at boot with Koala.configure so an empty options hash still resolves.
3. Verify the ENV variables exist in the failing environment by printing key names and value lengths, never the values.
4. Read options.inspect in the exception message; it shows exactly which keys were present or nil.

Example fix

// before
@updates = Koala::Facebook::RealtimeUpdates.new # relies on Koala.config, unset in this env

// after
@updates = Koala::Facebook::RealtimeUpdates.new(
  app_id: ENV.fetch("FACEBOOK_APP_ID"),
  app_access_token: ENV["FACEBOOK_APP_TOKEN"],
  secret: ENV.fetch("FACEBOOK_APP_SECRET")
)

def realtime_updates
  app_id = ENV["FACEBOOK_APP_ID"].to_s.strip
  secret = ENV["FACEBOOK_APP_SECRET"].to_s.strip
  raise KeyError, "FACEBOOK_APP_ID and FACEBOOK_APP_SECRET must be set" if app_id.empty? || secret.empty?
  Koala::Facebook::RealtimeUpdates.new(app_id: app_id, secret: secret)
end

When it happens

Trigger: RealtimeUpdates.new with an incomplete hash such as { app_id: 123 } carrying neither :secret nor :app_access_token; or an empty hash while Koala.config.app_id, .app_access_token, and .app_secret are all unset; or passing string keys where the lookup expects symbols. Typical root cause: ENV-backed config never loaded (Rails initializer order, missing .env in CI, renamed variables).

Common situations: Config that works in development but not in CI or production; ENV variables renamed during a migration; a Koala.configure block defined after the first RealtimeUpdates use; symbol and string key confusion when forwarding params.

Related errors

• build_url must get a callback either from the OAuth object o
• You must init RealtimeUpdates with your app secret in order
• generate_client_code received an error: empty response body
• Invalid (incomplete) signature data
• Unsupported algorithm #{envelope['algorithm']}

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