{"record":{"id":"d63b5d911f171e39","repo":"arsduo/koala","slug":"initialize-must-receive-a-hash-with-app-id-and-ei","errorCode":null,"errorMessage":"Initialize must receive a hash with :app_id and either :app_access_token or :secret! (received #{options.inspect})","messagePattern":"Initialize must receive a hash with :app_id and either :app_access_token or :secret! \\(received #(.+?)\\)","errorType":"validation","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"lib/koala/realtime_updates.rb","lineNumber":27,"sourceCode":"\n      attr_reader :app_id, :app_access_token, :secret\n\n      # Create a new RealtimeUpdates instance.\n      # If you don't have your app's access token, provide the app's secret and\n      # Koala will make a request to Facebook for the appropriate token.\n      #\n      # @param options initialization options.\n      # @option options :app_id the application's ID.\n      # @option options :app_access_token an application access token, if known.\n      # @option options :secret the application's secret.\n      #\n      # @raise ArgumentError if the application ID and one of the app access token or the secret are not provided.\n      def initialize(options = {})\n        @app_id = options[:app_id] || Koala.config.app_id\n        @app_access_token = options[:app_access_token] || Koala.config.app_access_token\n        @secret = options[:secret] || Koala.config.app_secret\n        unless @app_id && (@app_access_token || @secret) # make sure we have what we need\n          raise ArgumentError, \"Initialize must receive a hash with :app_id and either :app_access_token or :secret! (received #{options.inspect})\"\n        end\n      end\n\n      # The app access token, either provided on initialization or fetched from Facebook using the\n      # app_id and secret.\n      def app_access_token\n        # If a token isn't provided but we need it, fetch it\n        @app_access_token ||= Koala::Facebook::OAuth.new(@app_id, @secret).get_app_access_token\n      end\n\n      # The application API interface used to communicate with Facebook.\n      # @return [Koala::Facebook::API]\n      def api\n        # Only instantiate the API if needed. validate_update doesn't require it, so we shouldn't\n        # make an unnecessary request to get the app_access_token.\n        @api ||= API.new(app_access_token)\n      end\n","sourceCodeStart":9,"sourceCodeEnd":45,"githubUrl":"https://github.com/arsduo/koala/blob/47d052063ef8b5644fb59e279da0b52687999f55/lib/koala/realtime_updates.rb#L9-L45","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Pass credentials explicitly: RealtimeUpdates.new(app_id: ENV[\"FACEBOOK_APP_ID\"], secret: ENV[\"FACEBOOK_APP_SECRET\"]).","Or set the globals once at boot with Koala.configure so an empty options hash still resolves.","Verify the ENV variables exist in the failing environment by printing key names and value lengths, never the values.","Read options.inspect in the exception message; it shows exactly which keys were present or nil."],"exampleFix":"// before\n@updates = Koala::Facebook::RealtimeUpdates.new # relies on Koala.config, unset in this env\n\n// after\n@updates = Koala::Facebook::RealtimeUpdates.new(\n  app_id: ENV.fetch(\"FACEBOOK_APP_ID\"),\n  app_access_token: ENV[\"FACEBOOK_APP_TOKEN\"],\n  secret: ENV.fetch(\"FACEBOOK_APP_SECRET\")\n)","handlingStrategy":"validation","validationCode":"def realtime_updates\n  app_id = ENV[\"FACEBOOK_APP_ID\"].to_s.strip\n  secret = ENV[\"FACEBOOK_APP_SECRET\"].to_s.strip\n  raise KeyError, \"FACEBOOK_APP_ID and FACEBOOK_APP_SECRET must be set\" if app_id.empty? || secret.empty?\n  Koala::Facebook::RealtimeUpdates.new(app_id: app_id, secret: secret)\nend","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate required Facebook ENV variables in a boot initializer so a misconfigured process fails immediately with a clear message","Use ENV.fetch with explicit key names instead of ENV[...] so missing variables are loud","Keep one shared config module for Facebook credentials used by OAuth, API, and RealtimeUpdates"],"tags":["configuration","credentials","argumenterror","realtime-updates","koala","facebook"],"backgroundTag":"missing-api-credentials","analyzedSha":"47d052063ef8b5644fb59e279da0b52687999f55","analyzedAt":"2026-08-23T10:19:03.891Z","schemaVersion":2},"datasetVersion":"2026-08-23T13:39:53.451Z"}