Skip to main content
Last updated on

Troubleshoot Meta Ads ingestion

Beta

The Meta Ads connector is in Beta. Workspace admins can control access to this feature from the Previews page. See Manage Databricks previews.

This article describes common issues with the Meta Ads ingestion connector in Databricks Lakeflow Connect and how to resolve them.

General pipeline troubleshooting​

If a pipeline fails while executing, click on the step that failed and confirm whether the error message provides sufficient information about the nature of the error.

You can also check and download the cluster logs from the pipeline details page by clicking Update details in the right-hand panel, then Logs. Scan the logs for errors or exceptions.

Authentication failed​

Issue:

You receive an authentication error when creating a connection or running a pipeline.

Resolution:

  1. Check that your Meta app is configured correctly in the Meta Developer Portal.
  2. Confirm that the App ID and App Secret are entered correctly in the connection.
  3. Check that the OAuth redirect URI is configured correctly in the Meta app settings.
  4. Verify that the Meta app has the required permissions (ads_read, ads_management, business_management).
  5. If the error persists, try deleting and recreating the connection.

Rate limit exceeded​

Issue:

[SAAS_CONNECTOR_SOURCE_API_ERROR] An error occurred in the Meta API call. Error code: RATE_LIMIT_EXCEEDED.

This occurs when you hit an API rate limit in your Meta Ads account.

Resolution:

  1. Wait for your API limits to reset (typically 1 hour).
  2. Retry the pipeline.
  3. Consider reducing the frequency of your pipeline schedule.
  4. Consider splitting large pipelines into multiple smaller pipelines.

Invalid breakdown combination​

Issue:

[SAAS_CONNECTOR_SOURCE_API_ERROR] An error occurred in the Meta API call. Error code: INVALID_PARAMETER. Invalid breakdown combination.

This occurs when you configure an invalid breakdown or action breakdown combination for the ad_insights object.

Resolution:

  1. Review the Insights API documentation for valid breakdown combinations.
  2. Update your pipeline configuration to use a valid breakdown combination.
  3. Retry the pipeline.

Insufficient permissions​

Issue:

[SAAS_CONNECTOR_SOURCE_API_ERROR] An error occurred in the Meta API call. Error code: INSUFFICIENT_PERMISSIONS.

This occurs when the authenticating user doesn't have sufficient permissions to access the requested data.

Resolution:

  1. Verify that the Meta app has the required permissions in the Meta Developer Portal.
  2. Confirm that the authenticating user has access to the ad accounts you're trying to ingest.
  3. Check that the Meta app has completed the app review process if required.
  4. Reauthorize the connection if needed.

Expired access token​

Issue:

[SAAS_CONNECTOR_SOURCE_API_ERROR] An error occurred in the Meta API call. Error code: TOKEN_EXPIRED.

This occurs when the OAuth access token has expired.

Resolution:

  1. Edit the connection in Catalog Explorer.
  2. Reauthorize the connection by clicking Authenticate.
  3. Retry the pipeline.

The connector manages token refresh automatically, but in some cases, you may need to manually reauthorize the connection.

Ad account not found​

Issue:

[SAAS_CONNECTOR_SOURCE_API_ERROR] An error occurred in the Meta API call. Error code: ACCOUNT_NOT_FOUND.

This occurs when the specified ad account ID doesn't exist or the authenticating user doesn't have access to it.

Resolution:

  1. Verify that the ad account ID in the pipeline configuration is correct.
  2. Confirm that the authenticating user has access to the ad account in Meta Business Manager.
  3. Check that the ad account hasn't been deleted or deactivated.

Incomplete ad_insights data​

Issue:

The ad_insights table has missing or incomplete data for recent dates.

Resolution:

This is expected behavior. The ad_insights object uses attribution windows to account for delayed conversion events. Data for recent dates might be incomplete until the attribution window closes (seven days for click attribution, one day for view attribution).

The connector automatically ingests updated data on subsequent pipeline runs. No action is required.

Object or field not found​

Issue:

You can't find an expected object or field in the ingested data.

Resolution:

  1. Verify that the object or field name is correct. Object and field names are case-sensitive.
  2. Check that the authenticating user has permission to access the object or field.
  3. Confirm that the object or field is supported by the connector. See Meta Ads ingestion connector reference for a list of supported objects.
  4. Some fields may only be available with specific permissions or API versions.

Pipeline timeout​

Issue:

The pipeline times out during execution.

Resolution:

  1. Check if you're ingesting a large amount of data. Consider splitting the pipeline into smaller pipelines.
  2. Verify that your Meta API rate limits haven't been exceeded.
  3. Retry the pipeline. Some timeouts are transient.

If the issue persists, file a support ticket.

Next steps​