Skip to main content

Troubleshooting Knowledge Catalog connection and authentication issues

Resolve common connection and authentication issues when connecting Atlan to Google Cloud Knowledge Catalog.

WIF authentication fails​

Error

Missing required WIF credential fields or Authentication failed when using Workload Identity Federation

Cause​

One or more of the required WIF credential fields—service account email, WIF Pool Provider ID, Atlan OAuth Client ID, or Atlan OAuth Client Secret—is missing or incorrectly configured.

Solution​

  1. Verify all WIF fields are provided in the connector configuration:

    • Service Account Email: the email of the GCP service account to impersonate
    • WIF Pool Provider ID: in the format //iam.googleapis.com/projects/<project-number>/locations/global/workloadIdentityPools/<pool-id>/providers/<provider-id>
    • Atlan OAuth Client ID and Atlan OAuth Client Secret: from the OAuth client created in Atlan

  2. Verify the Workload Identity Pool OIDC provider is configured to trust your Atlan tenant issuer and that the Atlan OAuth Client ID is set as the audience.

  3. Verify roles/iam.workloadIdentityUser is granted on the service account to the workload identity principal set.

  4. Refer to Set up Workload Identity Federation for Google BigQuery for the detailed WIF configuration flow.

PSC connectivity issues​

Error

Connection timeout or Network error when using Private Service Connect

Cause​

The Private Service Connect endpoint isn't reachable, the DNS name is incorrect, or the endpoint isn't forwarding traffic to the Knowledge Catalog API.

Solution​

  1. Verify the Host entered in the Private Network Link connectivity option matches the DNS name provided by Atlan support.

  2. Verify the PSC endpoint is active and forwarding traffic to the Knowledge Catalog API service in Google Cloud.

  3. Verify DNS resolution of the PSC hostname is functioning from within the Atlan runtime network.

  4. If you haven't received a PSC DNS name yet, contact Atlan support to request one.

Service account key invalid​

Error

Invalid service account key or Authentication failed

Cause​

The service account key file is invalid, corrupted, deleted, or rotated in Google Cloud Console.

Solution​

  1. Verify the service account key file is valid JSON:

    cat <key-file-path> | jq .

  2. Verify the service account key exists and check if it was rotated in Google Cloud Console.

  3. Regenerate the service account key if needed:

    • Navigate to IAM & Admin → Service Accounts in Google Cloud Console
    • Select your service account
    • Go to Keys tab
    • Create a new key and update it in Atlan

Service account lacks required permissions​

Error

Permission denied or Insufficient permissions

Cause​

The service account doesn't have the required Knowledge Catalog permissions or the custom role assignment is incorrect.

Solution​

  1. Verify the service account has the custom role assigned:

    • Check IAM & Admin → IAM in Google Cloud Console
    • Confirm the service account email has the custom role attached

  2. Verify the custom role includes all required permissions:

    • Check IAM & Admin → Roles in Google Cloud Console
    • Review the custom role permissions
    • Add any missing permissions from the setup guide

  3. Verify the service account has access to the specific Knowledge Catalog resources (entry groups, entries) you're trying to crawl.

Cloud Dataplex API not enabled​

Error

API not enabled or Service unavailable

Cause​

The Cloud Dataplex API isn't enabled in your Google Cloud project.

Solution​

  1. Enable the Cloud Dataplex API in your Google Cloud project:

    • Navigate to APIs & Services → Library in Google Cloud Console
    • Search for "Cloud Dataplex API"
    • Click Enable

  2. Wait a few minutes for the API to fully activate before retrying the connection.

Invalid project ID​

Error

Project not found or Invalid project ID

Cause​

The project ID is incorrect or the service account belongs to a different project.

Solution​

  1. Verify the project ID is correct:

    • Check the project ID in Google Cloud Console
    • Check for typos or extra spaces

  2. Verify the service account belongs to the same project:

    • Check the service account email format: [email protected]
    • Verify the project ID matches

Network connectivity issues​

Error

Connection timeout or Network error

Cause​

Network connectivity issues between Atlan and Google Cloud, or Google Cloud service outages.

Solution​

  1. Verify network connectivity from Atlan to Google Cloud:

    • Check firewall rules if using VPC
    • Verify outbound HTTPS (443) is allowed

  2. Verify Google Cloud service status:

No assets found or fewer assets than expected​

Error

No assets found or fewer assets than expected after app completes

Cause​

The project ID is incorrect or the service account doesn't have access to the Knowledge Catalog entries in the specified project. The connector automatically searches across all locations within the project.

Solution​

  1. Verify the project ID is correct and contains Knowledge Catalog entries:

    • Open the Google Cloud console
    • Navigate to Knowledge Catalog and verify entries exist in the project

  2. Verify the service account has the required Knowledge Catalog permissions on the project (see the setup guide).

  3. Re-run the app after verifying the project configuration.

Preflight checks fail but connection works​

Error

Preflight check validation failed with specific validation errors

Cause​

Manual connection test succeeds but preflight checks fail. This indicates validation issues with API accessibility, authentication, or permissions.

Solution​

  1. Review the specific preflight check error message:

    • Connection validation: Check network and API enablement
    • Authentication: Verify service account key
    • Permissions: Verify IAM roles and permissions

  2. Run preflight checks again after addressing the specific issue.

See also​

Need help​

If you need assistance after trying the steps, contact Atlan support: Submit a request.