Troubleshooting

Alation Cloud Service Applies to Alation Cloud Service instances of Alation

Customer Managed Applies to customer-managed instances of Alation

Enhanced Connector Enhanced connectors add extended capabilities and require a separate entitlement in addition to your Alation platform license.

Connection Fails with “Failed to connect to Sigma API”

Problem

You are configuring a new Sigma BI source or running a test connection from the General Settings tab. When you click Test, the connection fails.

On the connector Settings page, the test connection shows an error indicating the Sigma API cannot be reached.

The connection test does not complete, and you cannot proceed with metadata extraction.

Cause

The connection failure occurs when:

  • The Sigma Web URL does not end with a forward slash (/).

  • The Sigma API URL does not match your Sigma cloud provider.

  • The Client ID or Client Secret is incorrect or inactive.

  • Network connectivity to Sigma endpoints is blocked.

Solution

  1. Verify the Sigma Web URL ends with a forward slash (/).

  2. Verify the Sigma API URL ends with .com/ and matches your cloud provider:

    • GCP: https://api.sigmacomputing.com/

    • AWS US: https://aws-api.sigmacomputing.com/

    • AWS Canada: https://api.ca.aws.sigmacomputing.com/

    • AWS Europe: https://api.eu.aws.sigmacomputing.com/

    • Azure: https://api.us.azure.sigmacomputing.com/

  3. Ensure the Client ID and Client Secret are correct and active in the Sigma Admin Portal.

  4. Check network connectivity to Sigma endpoints from the Alation Connector Manager or Alation Agent.

  5. Re-run the test connection.

Authentication Fails with “Invalid Credentials”

Problem

You are running metadata extraction (MDE) or testing the connection on a Sigma BI source. The job fails with an authentication error.

On the connector Settings > Metadata Extraction > Job History tab, the job shows the status FAILED. The error indicates invalid or expired credentials.

Metadata extraction does not complete, and no objects are ingested into the catalog.

Cause

Authentication failure occurs when:

  • The Client ID or Client Secret is incorrect.

  • The API credentials have expired or been revoked.

  • The credentials do not have the required permissions (Admin-level required for Permission Mirroring).

Solution

  1. Verify the Client ID and Client Secret in the Sigma Admin Portal under API & Embed Secrets.

  2. Ensure the API credentials have not expired.

  3. Check that the credentials have appropriate permissions. Admin-level access is required for Permission Mirroring.

  4. If the credentials have expired, generate a new API token and update the connector settings.

  5. Re-run metadata extraction.

MDE Completes but Some Objects Are Missing

Problem

You have completed metadata extraction (MDE) on a Sigma BI source. The job shows status SUCCEEDED or PARTIAL SUCCESS, but some workbooks, pages, or elements are not appearing in the Alation catalog.

On the connector Settings > Metadata Extraction > Job History tab, the job completes without errors, but when you browse the Sigma source in the catalog, expected objects are missing.

Cause

Objects may be missing from extraction when:

  • Explicit Tags filtering is configured, and the missing objects do not have matching tags.

  • The service account does not have access to the workspaces containing the missing objects.

  • Objects are in personal workspaces with restricted access.

  • Permission Mirroring is enabled, and the user viewing the catalog does not have Sigma permissions for those objects.

Solution

  1. Check if Explicit Tags filtering is configured in General Settings > Advanced Connector Features. Only objects with matching tags are extracted.

  2. Verify the service account has access to the workspaces containing the missing objects in Sigma.

  3. Check if objects are in personal workspaces that may have restricted access.

  4. If using Permission Mirroring, verify the Alation user has corresponding permissions in Sigma.

  5. Re-run metadata extraction after adjusting settings.

Permission Mirroring Not Working Correctly

Problem

You have enabled Permission Mirroring for a Sigma BI source, but users are seeing all objects regardless of their Sigma permissions, or users are not seeing objects they should have access to.

On the Sigma source catalog page, the object visibility does not match the expected Sigma permissions.

Cause

Permission Mirroring issues occur when:

  • The connector is not using Admin-level API credentials.

  • CSV Identity Mapping file has incorrect or missing entries.

  • Alation usernames do not match Sigma email addresses (when CSV Identity Mapping is not used).

  • Permission Mirroring is not enabled in connector settings.

Solution

  1. Ensure Permission Mirroring is enabled in General Settings > Advanced Connector Features.

  2. Verify the connector is using Admin-level API credentials in Sigma.

  3. If using CSV Identity Mapping:

    • Verify the CSV file format: network_id,sigma_email

    • Ensure all Alation users have corresponding Sigma email entries

    • Check for typos in email addresses

  4. Without CSV Identity Mapping, ensure Alation usernames match Sigma email addresses exactly.

  5. Re-run metadata extraction to refresh permissions.

MDE is Slow or Times Out

Problem

You are running metadata extraction (MDE) on a Sigma BI source with a large number of workspaces and workbooks. The extraction takes an unusually long time or times out.

On the connector Settings > Metadata Extraction > Job History tab, the job runs for an extended period or fails due to timeout.

Cause

Slow extraction performance occurs when:

  • The API Concurrency Level is set too low for the environment size.

  • A large number of objects are being extracted without filtering.

  • Network bandwidth is limited.

  • Sigma API rate limits are being hit frequently.

Solution

  1. Increase the API Concurrency Level in General Settings > Advanced Connector Features. Default is 3, maximum is 10. Use 3-5 for shared Sigma instances, up to 10 for dedicated instances.

  2. Use Explicit Tags in General Settings > Advanced Connector Features to filter and extract only relevant objects.

  3. Use Selective Extraction to limit extraction to specific workspaces.

  4. Enable Network Throttle only if experiencing bandwidth issues.

  5. Schedule extractions during off-peak hours.

Lineage Not Appearing in Catalog

Problem

You have completed metadata extraction (MDE) on a Sigma BI source, but lineage relationships are not displayed for page elements in the Alation catalog.

On the catalog page for a Sigma workbook or page element, the lineage tab shows no upstream or downstream connections.

Cause

Lineage may not appear when:

  • Disable Automatic Lineage Generation is enabled in Application Settings.

  • The page elements do not have actual data source connections in Sigma.

  • The connected data sources are not cataloged in Alation.

  • The extraction did not complete successfully.

Solution

  1. Ensure Disable Automatic Lineage Generation is unchecked in General Settings > Application Settings.

  2. Verify the page elements have actual data source connections in Sigma.

  3. Check that the connected data sources are also cataloged in Alation.

  4. Run a full metadata extraction to refresh lineage relationships.

Rate Limit Errors (HTTP 429)

Problem

You are running metadata extraction (MDE) on a Sigma BI source. The extraction fails or slows down significantly due to rate limit errors.

On the connector logs or job history, you see HTTP 429 errors indicating the Sigma API rate limit has been exceeded.

Cause

Rate limit errors occur when the connector makes too many API requests in a short period. This typically happens when:

  • The API Concurrency Level is set too high.

  • Extracting a large number of objects simultaneously.

  • Running multiple extractions concurrently.

The connector automatically retries rate-limited requests (up to 12 hours with 2-second intervals), but excessive rate limiting can significantly slow extraction.

Solution

  1. Reduce the API Concurrency Level in General Settings > Advanced Connector Features. Try reducing from 10 to 3-5.

  2. Schedule extractions during off-peak hours when fewer users are accessing Sigma.

  3. Use Explicit Tags to reduce the number of objects extracted.

  4. If running multiple connectors, stagger their extraction schedules.

Reference Information

API Endpoints

The connector uses the following Sigma REST APIs:

Authentication:

  • POST /v2/auth/token - Obtain access token

  • GET /v2/whoami - Get authenticated user info

Metadata Extraction:

  • GET /v2/workspaces - List workspaces

  • GET /v2/workspaces/{workspaceId}/grants - Get workspace permission grants

  • GET /v2/members - List users/members

  • GET /v2/members/{memberId}/files - List member’s files

  • GET /v2/workbooks/{workbookId}/pages - List pages in a workbook

  • GET /v2/workbooks/{workbookId}/pages/{pageId}/elements - List page elements

  • GET /v2/connections - List data connections

  • GET /v2/datasets/{datasetId}/sources - Get dataset sources

  • GET /v2/tags - List tags

  • GET /v2/teams/{teamId} - Get team info

Lineage:

  • GET /v2/workbooks/{workbookId}/lineage/elements/{elementId} - Get element lineage

Object Preview:

  • POST /v2/workbooks/{workbookId}/export - Initiate workbook export

  • GET /v2/query/{queryId}/download - Download export result

Extraction Job Status

Status

Description

Did Not Start

The extraction did not start due to configuration issues.

Succeeded

The extraction completed successfully.

Partial Success

The extraction completed with warnings. Some objects were skipped.

Failed

The extraction failed with errors. Check logs for details.

Collecting Diagnostic Information

When contacting support, collect the following:

  1. Connector logs (set Log Level to DEBUG in General Settings > Connector Settings)

  2. Extraction job history and error messages from the Job History tab

  3. Sigma workspace and workbook counts

  4. Cloud provider (GCP, AWS, Azure) and region information

  5. Screenshots of configuration settings (without credentials)