`KeyError: 'fbtrace_id'` when sending event with `ActionSource.APP`

[bdoms]

Everything is working well for us with this SDK, except that we encounter a bug every time we try to set the action source as ActionSource.APP. Changing all the other fields doesn't produce this problem and we can see events coming through correctly.

Given a setup like this:

import os
import uuid

from facebook_business.adobjects.serverside.action_source import ActionSource
from facebook_business.adobjects.serverside.custom_data import CustomData
from facebook_business.adobjects.serverside.event import Event
from facebook_business.adobjects.serverside.event_request_async import EventRequestAsync
from facebook_business.adobjects.serverside.user_data import UserData
from facebook_business.api import FacebookAdsApi

FacebookAdsApi.init(access_token=os.environ['FACEBOOK_ACCESS_TOKEN'])

And then a function that does this:

user_data = UserData(email='user@example.com', phone='+15555550000',
    client_ip_address='127.0.0.1', client_user_agent='a valid user agent')

custom_data = CustomData(currency='usd', value=9.99)

event = Event(
    event_name='Purchase',
    event_time=int(time.time()),
    event_id=f'{event_name}-{uuid.uuid4()}',
    user_data=user_data,
    custom_data=custom_data,
    data_processing_options=[],
    event_source_url='https://www.example.com/checkout',
    action_source=ActionSource.APP
)

event_request_async = EventRequestAsync(events=[event], pixel_id=os.environ['FACEBOOK_PIXEL_ID'])
await event_request_async.execute()

That last lines fails with

File "[redacted]/python3.13/site-packages/facebook_business/adobjects/serverside/event_request_async.py", line 99, in execute
    fbtrace_id=response['fbtrace_id'],
               ~~~~~~~~^^^^^^^^^^^^^^
KeyError: 'fbtrace_id'

Again, it seems like none of the data we're including matters except for the action_source. If it's ActionSource.WEBSITE then this will work correctly without an error every time.

Looking at that line of code here: https://github.com/facebook/facebook-python-business-sdk/blob/main/facebook_business/adobjects/serverside/event_request_async.py#L99

It seems like it's making some assumptions about what's included in the response, when maybe it should be more careful?

[dkranchii]

Recommended Solution:

Understanding the Error:

KeyError: 'fbtrace_id'
occurs at line 99 of event_request_async.py because the Facebook Python Business SDK assumes a response structure that does not always exist.
Why This Happens
Different Response Formats
ActionSource.WEBSITE → Consistently includes fbtrace_id
ActionSource.APP → May omit fbtrace_id (especially in certain configurations or regions)
SDK Assumption
fbtrace_id = response['fbtrace_id'] # Line 99 in event_request_async.py
This fails when the key is missing.

Impact
The error crashes your application.
Events are still successfully sent to Facebook.
fbtrace_id is primarily used for debugging and tracing.

ActionSource Differences Explained:

ActionSource.WEBSITE
Required fields: client_user_agent, event_source_url
Response: Always includes fbtrace_id
Use case: Browser-based tracking
Reliability: High consistency

ActionSource.APP
Required fields: Mobile app identifiers
Response: May exclude fbtrace_id
Use case: In-app purchases, mobile events
Variability: Response format may vary

Why APP Events Differ
Mobile events use different processing pipelines at Facebook, and trace IDs are not always generated.
Common scenarios:
Cross-platform mobile apps
Certain geographic regions
Specific app configurations
Production-Ready Solution:
Create a patched version of EventRequestAsync that safely handles missing fbtrace_id.

Patched Implementation

import os
import uuid
import time
from facebook_business.adobjects.serverside.action_source import ActionSource
from facebook_business.adobjects.serverside.custom_data import CustomData
from facebook_business.adobjects.serverside.event import Event
from facebook_business.adobjects.serverside.event_request_async import EventRequestAsync
from facebook_business.adobjects.serverside.user_data import UserData
from facebook_business.adobjects.serverside.event_response import EventResponse
from facebook_business.api import FacebookAdsApi

class PatchedEventRequestAsync(EventRequestAsync):
"""
Patched version of EventRequestAsync that handles missing fbtrace_id gracefully.
Drop-in replacement for the original EventRequestAsync class.
"""

async def execute(self):
    """
    Execute the event request with safe fbtrace_id handling.
    """
    try:
        request = self._build_request()
        response_dict = await request.execute_async()
        return self._create_safe_response(response_dict)

    except Exception as e:
        print(f"Warning: EventRequestAsync execution error: {e}")
        return self._create_empty_response()

def _create_safe_response(self, response_dict):
    """
    Create EventResponse with safe field extraction.
    """
    events_received = response_dict.get('events_received', 0)
    messages = response_dict.get('messages', [])
    fbtrace_id = response_dict.get('fbtrace_id', 'N/A-APP-EVENT')

    return EventResponse(
        events_received=events_received,
        messages=messages,
        fbtrace_id=fbtrace_id
    )

def _create_empty_response(self):
    """
    Create empty response for error scenarios.
    """
    return EventResponse(
        events_received=0,
        messages=["Error occurred during request execution"],
        fbtrace_id="ERROR-NO-TRACE"
    )

Usage Example
async def send_app_event_safely():
FacebookAdsApi.init(access_token=os.environ['FACEBOOK_ACCESS_TOKEN'])

user_data = UserData(
    email='user@example.com',
    phone='+15555550000',
    client_ip_address='127.0.0.1',
    client_user_agent='MyApp/1.0 (iOS)'
)

custom_data = CustomData(currency='USD', value=9.99)

event = Event(
    event_name='Purchase',
    event_time=int(time.time()),
    event_id=f'Purchase-{uuid.uuid4()}',
    user_data=user_data,
    custom_data=custom_data,
    action_source=ActionSource.APP  # Now works safely
)

event_request = PatchedEventRequestAsync(
    events=[event],
    pixel_id=os.environ['FACEBOOK_PIXEL_ID']
)

response = await event_request.execute()

print(f"Events received: {response.events_received}")
print(f"FB Trace ID: {response.fbtrace_id}")

return response

Conclusion:
fbtrace_id is optional for ActionSource.APP
The SDK incorrectly assumes it always exists
Safe .get() handling prevents crashes
Events are not lost — only debugging metadata may be missing