Skip to main content

Troubleshooting Dataplex connection and authentication issues

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

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 Dataplex 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 Dataplex catalog resources (entry groups, entries) you're trying to crawl.

Dataplex API not enabled​

Error

API not enabled or Service unavailable

Cause​

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

Solution​

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

    • Navigate to APIs & Services → Library in Google Cloud Console
    • Search for "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 location configuration doesn't cover all locations where your Dataplex entries exist. Each location type determines the search scope:

  • global searches all GCP locations
  • A multi-region such as us or eu searches all regions within that multi-region
  • A single region such as us-central1 searches only that specific region

If you specify us-central1 but your entries exist in us-east1, the connector doesn't discover those entries.

Solution​

  1. Verify which locations contain your Dataplex entries:

    • Open the Google Cloud console
    • Navigate to Dataplex and review the locations of your entry groups and entries

  2. Re-run the app after updating the location.

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.