source-facebook-pages: Sync fails with 'Bad request' when user has limited OAuth permissions

[devin-ai-integration]

Summary

The Facebook Pages connector fails during sync with a "Bad request" error when users authenticate with limited OAuth permissions. This happens because the connector requests over 100 fields for the page stream, many of which require elevated permissions beyond the basic pages_read_engagement and pages_read_user_content.

Problem

When a user authenticates with Facebook and only has basic permissions (not admin-level access to the Page), the OAuth flow shows fewer permission requests. However, the connector still attempts to request all fields, including those that require elevated permissions. Facebook returns a "Bad request" error instead of gracefully ignoring inaccessible fields.

Error message:

Exception while syncing stream page: Bad request. Please check your request parameters.

Root Cause Analysis

The page stream in manifest.yaml requests the following fields that require elevated permissions:

Fields requiring pages_manage_metadata or admin access

• page_token - Requires admin role
• access_token - Requires a role on the Page
• unread_message_count, unread_notif_count, unseen_message_count - Requires messaging/admin access
• leadgen_tos_acceptance_time, leadgen_tos_accepted, leadgen_tos_accepting_user - Requires lead gen permissions
• is_webhooks_subscribed - Requires admin access

Fields requiring pages_manage_ads

• ad_campaign - Requires ads permissions
• messenger_ads_default_icebreakers, messenger_ads_default_quick_replies, messenger_ads_quick_replies_type - Requires messenger ads permissions
• promotion_eligible, promotion_ineligible_reason - Requires ads permissions

Edge fields (connections) that may require additional permissions

• albums, call_to_actions, canvas_elements, events, feed, global_brand_children, image_copyrights, indexed_videos, likes, live_videos, photos, posts, published_posts, tabs, tagged, rtb_dynamic_posts, video_lists, videos

OAuth Scopes Requested vs Required

The connector requests these OAuth scopes:

pages_manage_ads, pages_manage_metadata, pages_read_engagement, pages_read_user_content, read_insights, catalog_management

However, Facebook only grants permissions the user actually has on their Page(s). Users with limited Page access (e.g., analyst or editor roles) will not receive pages_manage_ads, pages_manage_metadata, or catalog_management permissions, even though Airbyte requests them.

Expected Behavior

The connector should work with basic permissions (pages_read_engagement, pages_read_user_content) and gracefully handle cases where elevated permissions are not available.

Proposed Solutions

1. Reduce default field list: Only request fields that work with basic permissions by default
2. Make advanced fields configurable: Add a config option to enable/disable advanced fields
3. Graceful degradation: Implement error handling to retry with fewer fields when a "Bad request" occurs
4. Better documentation: Clearly document which permissions are required for which features

Related Issues

• source-facebook-pages: CHECK error message missing catalog_management permission requirement #70893 - CHECK error message missing catalog_management permission requirement

Environment

• Connector: source-facebook-pages
• Version: 2.0.4
• Manifest location: airbyte-integrations/connectors/source-facebook-pages/source_facebook_pages/manifest.yaml

---

Requested by: teo@airbyte.io (@tgonzalezc5)
Investigated by: Devin AI - https://app.devin.ai/sessions/056d8dd22277481dad7601a5cfca2dcb

---

Internal Tracking: https://github.com/airbytehq/oncall/issues/11143

[octavia-bot]

AI Triage Starting...

Thank you for opening this issue! I'm an AI assistant that will help with initial triage.

I'll review your issue and:

• Ask clarifying questions if needed
• Provide immediate guidance if available
• Escalate to the appropriate team if this requires engineering attention

View playbook

• 🔗 Session URL: https://app.devin.ai/sessions/06fa720de30141e78961fdeff585b810

✅ Devin AI session created successfully!

[devin-ai-integration]

Hi @tgonzalezc5, thank you for reporting this issue!

I have reviewed the connector code and confirmed the root cause. The page stream in the manifest requests over 100 fields, many of which require elevated permissions beyond the basic pages_read_engagement and pages_read_user_content scopes. When a user authenticates with limited Page permissions (e.g., analyst or editor roles), Facebook returns a "Bad request" error instead of gracefully ignoring inaccessible fields.

Confirmed problematic fields include:

• page_token, is_webhooks_subscribed (require admin access)
• leadgen_tos_* fields (require lead gen permissions)
• unread_message_count, unread_notif_count, unseen_message_count (require messaging/admin access)
• messenger_ads_* fields, ad_campaign, promotion_eligible, promotion_ineligible_reason (require ads permissions)

Additionally, the current error handler has a RETRY action for HTTP 400 errors, which causes the connector to keep retrying instead of failing gracefully when permission issues occur.

I am escalating this to our internal oncall team for further investigation and a fix. I will update this issue with the tracking link shortly.

---

This message is generated from Devin.ai (internal session link).

[devin-ai-integration]

This issue has been escalated to our internal oncall team for further investigation.

Internal Tracking: https://github.com/airbytehq/oncall/issues/11143

We will provide updates as the investigation progresses. In the meantime, users experiencing this issue can work around it by ensuring they have full admin access to the Facebook Page they are trying to sync.

---

This message is generated from Devin.ai (internal session link).

[devin-ai-integration]

Updated Analysis: CHECK vs Sync Behavior

After further investigation, I want to clarify the relationship between CHECK and sync operations:

Why CHECK Passes but Sync Fails

CHECK behavior: The connector's CHECK operation is hardcoded to only test the post stream (see manifest.yaml lines 351-353):

check:
  stream_names:
    - "post"

The post stream works with basic permissions (pages_read_engagement, pages_read_user_content), so CHECK passes even for users with limited OAuth permissions.

Sync behavior: During sync, the connector attempts to sync ALL enabled streams, including the page stream. The page stream requests over 100 fields, many of which require elevated permissions. When Facebook receives a request for fields the access token can't access, it returns a "Bad request" error.

The Incomplete Fix in PR #72253

PR #72253 removed product_catalogs from the field request, which addressed one problematic field. However, many other fields that require elevated permissions remain in the page stream definition.

Recommended Fix

The page stream in manifest.yaml should be updated to remove or make optional all fields that require permissions beyond pages_read_engagement and pages_read_user_content. This includes:

Fields to remove (require pages_manage_metadata or admin access):

• page_token, access_token
• unread_message_count, unread_notif_count, unseen_message_count
• leadgen_tos_acceptance_time, leadgen_tos_accepted, leadgen_tos_accepting_user
• is_webhooks_subscribed

Fields to remove (require pages_manage_ads):

• ad_campaign
• messenger_ads_default_icebreakers, messenger_ads_default_quick_replies, messenger_ads_quick_replies_type
• promotion_eligible, promotion_ineligible_reason

Edge fields to evaluate (may require additional permissions):

• albums, call_to_actions, canvas_elements, events, feed, global_brand_children, image_copyrights, indexed_videos, likes, live_videos, photos, posts, published_posts, tabs, tagged, rtb_dynamic_posts, video_lists, videos

This would be similar to what was done for product_catalogs but covering all the other problematic fields.

[darynaishchenko]

more details in slack - https://airbytehq-team.slack.com/archives/C07N1EGSM8E/p1770210491802279?thread_ts=1763659755.649749&cid=C07N1EGSM8E

same community issue - https://developers.facebook.com/community/threads/208937904236305/

We can either remove the field from the request or update our oauth app.

[darynaishchenko]

tested dev version that removes live_videos field from the page stream request https://cloud.airbyte.com/workspaces/11ff1132-3d09-4d07-a2ef-27ceaf8d9d4c/connections/cf2744c0-82f6-4b60-9453-a48b2ada2f8e/timeline?eventId=2a4820f5-aa89-47c2-ad53-afe6b1d6cee3&openLogs=true