Troubleshoot the Google Analytics Aggregated connector

Beta

This feature is in Beta. To use it, a workspace admin must turn on Lakeflow Connect for Google Analytics Aggregated from the Previews page. See Manage Databricks previews.

Resolve permission (403), request (400), expired token (401), quota (429), and transient server errors from the managed Google Analytics Aggregated connector in Lakeflow Connect.

For general troubleshooting guidance that applies to all managed ingestion pipelines, see Troubleshoot managed ingestion pipelines.

Permission denied (403)

Error message:

The pipeline fails with an HTTP 403 response, and the error is classified as a configuration error.

Cause: The authenticated identity can't access the Google Analytics 4 (GA4) property, or the Google Analytics Data API isn't enabled in the Google Cloud project that owns the credentials.

Solution:

1. Confirm that the Google Analytics Data API is enabled in the Google Cloud project. See Enable the Google Analytics Data API.
2. Confirm that the identity has at least the Viewer role on every property in property_ids or property_id:
   • For a service account that uses its own identity, add the service account's email address to each property. See Grant the service account access to your properties.
   • For a service account that uses domain-wide delegation, confirm that the User Email to Impersonate user has access to each property, and that the https://www.googleapis.com/auth/analytics.readonly scope is authorized for the service account's client ID.
   • For OAuth user-to-machine (U2M), confirm that the user who signed in has access to each property.

To update credentials, edit the connection in Catalog Explorer. See Create a Google Analytics Aggregated connection.

Invalid request (400)

Error message:

The pipeline fails with an HTTP 400 response, and the error is classified as a configuration error.

Cause: The Google Analytics Data API rejected the report request. Common causes include a property ID that isn't numeric, or a custom report whose dimensions and metrics include an unknown API name or an incompatible combination.

Solution:

• Confirm that each property ID is the numeric GA4 property ID. See Property ID in the Google documentation.
• For a custom_report object, confirm that each value in dimensions and metrics is a valid API name listed in API Dimensions & Metrics. Check the combination with Method: properties.checkCompatibility.
• Confirm that dimensions, metrics, and property_ids are JSON array strings, for example '["country"]'. See Examples.

Access token expired (401)

Error message:

The pipeline fails with an HTTP 401 response.

Cause: The access token that the connection uses expired or was revoked.

Solution:

The connector automatically refreshes the access token and retries when it receives a 401 response. If the error persists:

• For OAuth U2M connections, re-authenticate by editing the connection in Catalog Explorer and completing the sign-in flow again. If the OAuth app uses the External user type with the Testing publishing status, Google refresh tokens expire after 7 days. See Configure the OAuth consent screen.
• For service account connections, confirm that the service account key in the connection exists in the Google Cloud console. If the key was deleted, create a key and update the connection.

Quota exhausted (429)

Error message:

The pipeline reports HTTP 429 responses from the Google Analytics Data API.

Cause: The pipeline used up one of the property's Data API quotas, such as tokens per hour or concurrent requests.

Solution:

The connector automatically backs off and retries rate-limited requests. If the pipeline continues to fail, reduce the number of tables or properties in a single pipeline, set a later start_date, or schedule pipeline runs less often. For quota limits, see Limits and quotas in the Google documentation.

Transient server errors (500, 502, 503, 504)

Error message:

The pipeline fails with an HTTP 500, 502, 503, or 504 response.

Cause: The Google Analytics Data API returned a temporary server error that isn't related to your credentials or pipeline configuration.

Solution:

The connector automatically retries transient errors with exponential backoff. If the pipeline continues to fail after retries, rerun the pipeline later.