Skip to main content
Last updated on

Troubleshoot Gmail ingestion

This page describes common issues with the Gmail ingestion connector in Databricks Lakeflow Connect and how to resolve them.

Beta

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

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

Authentication error (401)​

A 401 response means the connector could not authenticate to Gmail with the service account. Check the following:

  1. Confirm that you pasted the complete, unmodified service account JSON key when you created the Unity Catalog connection. A truncated or malformed key causes authentication to fail.
  2. Confirm that the service account has domain-wide delegation authorized for the https://www.googleapis.com/auth/gmail.readonly scope in the Google Admin Console. See Grant domain-wide delegation.
  3. Confirm that the mailbox you're impersonating exists and is within the Google Workspace domain that the service account is authorized to delegate for.
  4. If you rotated or deleted the service account key, create a new key and update the connection.

Quota or rate-limit error (429 or 403)​

Gmail enforces per-user and per-project API quotas. When Gmail returns an HTTP 403 response, the connector reads the Retry-After header (with a minimum backoff of 1 second) and retries the request automatically, so transient rate limiting usually resolves without action.

If a pipeline continues to fail with quota errors:

  • Reduce the pipeline schedule frequency to lower API usage.
  • Confirm that the Gmail API is enabled and that your Google Cloud project quota is sufficient in the Google Cloud console under APIs & Services > Quotas.

historyId expiry​

The messages and message_labels tables use a stored historyId cursor for incremental sync. If the pipeline runs less often than Gmail's history retention window, Gmail expires the cursor and the History API returns a 404. In this case, the connector automatically falls back to a full refresh of the affected table, so no action is required. To avoid full refreshes, schedule the pipeline to run frequently enough that the cursor stays within Gmail's retention window.

Get help​

If an issue persists after following these troubleshooting steps, file a support ticket.

On this page