Skip to main content
Last updated on

Troubleshoot the Workiva connector

Beta

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

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

Workiva credentials missing a required scope​

Cause: Workiva returned an HTTP 403 response because the OAuth2 application is not authorized for the requested resource. The connector treats this as a configuration error and fails the pipeline. A common cause is an application that is missing the activity:read scope (required for activities) or the organization:read scope (required for users and roles).

Solution:

  1. In your Workiva organization, confirm that the OAuth2 application has both the activity:read and organization:read scopes.
  2. If you add a scope, generate updated credentials if required, then update the Unity Catalog connection with the new Client ID and Client Secret.
  3. Run the pipeline again.

For details, see Configure authentication to Workiva.

Workiva access token rejected​

Cause: Workiva returned an HTTP 401 response. The access token expired or the client credentials are incorrect. The connector automatically refreshes the token and retries once; if the retry still fails, the pipeline fails with an invalid-credentials error.

Solution:

  1. Confirm that the Client ID and Client Secret in the Unity Catalog connection match a current, active Workiva OAuth2 application.
  2. Confirm that the Organization ID in the Unity Catalog connection matches your Workiva organization.
  3. If the credentials are incorrect or revoked, create new credentials in Workiva, update the connection, and run the pipeline again.

For details, see Configure authentication to Workiva.

Workiva API rate limit exceeded​

Cause: Workiva returned an HTTP 429 response because the request rate exceeded the API's limit.

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 Workiva OAuth2 application.

Workiva API temporarily unavailable​

Cause: Workiva 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.

On this page