Troubleshoot the Google Workspace connector

Important

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

This page describes common errors you might encounter with the managed Google Workspace connector and how to resolve them.

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

Token minting fails with invalid_scope or unauthorized_client

Cause: The scope requested for the OAuth token doesn't match the scope authorized in your Google Workspace Admin console or OAuth consent screen. Google rejects token minting with invalid_scope or unauthorized_client.

Solution:

1. In the Google Workspace Admin console, go to Security > Access and data control > API controls (or your organization's equivalent OAuth management interface).
2. Confirm that the OAuth client from your connection is authorized for the https://www.googleapis.com/auth/admin.reports.audit.readonly scope.
3. Confirm that the OAuth Scope in the Unity Catalog connection matches the authorized scope exactly: https://www.googleapis.com/auth/admin.reports.audit.readonly.

For details, see Configure authentication to Google Workspace.

Pipeline fails to authenticate

Cause: Google Workspace returned an HTTP 403 response that isn't a rate-limit response. This usually means the OAuth token is invalid, expired, or the scope wasn't properly authorized. The connector treats this as a configuration error and fails the pipeline.

Solution:

1. Confirm that the Client ID, Client Secret, Authorization Endpoint, and Token Endpoint in the Unity Catalog connection are correct and match the OAuth client created in your Google Cloud project.
2. Confirm that the OAuth Scope is exactly https://www.googleapis.com/auth/admin.reports.audit.readonly.
3. If the token has expired, trigger a new authorization flow to obtain a fresh token.

For details, see Configure authentication to Google Workspace.

Google Workspace API rate limit exceeded

Cause: Google Workspace returned an HTTP 429 response, or an HTTP 403 response with a rateLimitExceeded or userRateLimitExceeded reason, because the connector sent too many requests in a short period.

Solution:

The connector honors the Retry-After response header, then falls back to exponential backoff and retries automatically. If this happens repeatedly, reduce the pipeline's schedule frequency or the number of concurrent pipelines that share the same Google Workspace account.

Google Workspace API temporarily unavailable

Cause: Google Workspace returned a transient server error (HTTP 500, 502, 503, or 504).

Solution:

The connector automatically retries with exponential backoff. If the issue persists, wait, then run the pipeline again.