Skip to main content

Starburst Enterprise FAQ

This page covers frequently asked questions and troubleshooting guidance for the Starburst Enterprise connector.

Known behaviors​

Data product status mapping​

Starburst Enterprise has three data product states: Published, Draft, and Pending Changes. Atlan maps these as follows:

Starburst Enterprise statusAtlan status
PublishedActive
Pending ChangesActive
DraftDraft

The "Pending Changes" state is mapped to "Active" because Atlan's DataProduct status doesn't have an equivalent state. The distinction between Published and Pending Changes isn't preserved.

Domains and data products are global assets​

Domains and data products are global assets in Atlan—they exist outside any specific connection. Datasets and dataset columns, however, belong to the connection that created them.

This only causes issues when two or more Starburst Enterprise connections in the same Atlan tenant have domains and data products with the same names. In that case, both connections publish their datasets under the same global data product, resulting in a higher dataset count in Atlan than in either Starburst instance.

For example, if you set up two connections—one for a production Starburst cluster and one for staging—and both have a domain called Analytics with a data product called Customer360 containing 3 datasets, Atlan creates a single global Customer360 data product. Each connection publishes its own datasets under that data product, so Atlan shows 6 datasets instead of the 3 visible in either Starburst instance.

Materialized view detection​

Starburst Enterprise's INFORMATION_SCHEMA tables report materialized views as BASE TABLE due to a known Trino limitation. The connector queries system.metadata.materialized_views separately to correctly classify these assets, but this requires access to the system catalog.

Troubleshooting​

Authentication fails during test connection​

Symptoms: The Test Authentication step fails with a connection error or permission denied.

Possible causes and solutions:

  • Incorrect credentials: Verify the username and password are correct. For LDAP authentication, confirm the user can log in to the Starburst Enterprise UI directly.
  • Wrong role: The default role is sysadmin. If you created a dedicated role (for example, atlan_metadata_reader), make sure to enter that role name in the Role field.
  • Port mismatch: The default port is 443 for HTTPS. Some deployments use custom ports (for example, 8443 or 8080). Confirm the correct port with your Starburst administrator.
  • SSL certificate issues: If your instance uses self-signed certificates, set Verify SSL to False. For production, install the CA certificate and keep SSL verification enabled.

Preflight checks pass but extraction fails​

Symptoms: Preflight checks report success, but the crawler workflow fails during metadata extraction.

Possible causes and solutions:

  • Insufficient permissions: Preflight checks validate basic connectivity (listing catalogs and domains), but extraction queries INFORMATION_SCHEMA tables across catalogs. Verify the user has SHOW privileges on tables in each catalog you want to crawl.
  • Catalog-specific failures: The connector isolates failures per catalog—one inaccessible catalog doesn't block the rest. Check the workflow logs to identify which catalog failed and verify permissions for that catalog.

Some catalogs or schemas are missing from extraction​

Symptoms: The crawler completes successfully, but expected catalogs or schemas don't appear in Atlan.

Possible causes and solutions:

  • Catalog filter applied: Check whether specific catalogs were selected in the crawler configuration. If a catalog isn't in the selection, it won't be crawled.
  • Missing privileges: In BIAC, INFORMATION_SCHEMA only returns rows for objects the user has at least one privilege on. Grant SHOW on tables in the missing catalog.
  • Catalog state: The connector only crawls catalogs reported by system.metadata.catalogs. Verify the missing catalog appears in that table when queried as the Atlan user.

Materialized views appear as tables​

Symptoms: Materialized views are cataloged as regular tables in Atlan.

Possible causes and solutions:

  • Missing system catalog access: The connector queries system.metadata.materialized_views to detect materialized views. If the Atlan user can't access this table, materialized views are classified as BASE TABLE by default. Grant SELECT on system.metadata.materialized_views.

Domains or data products aren't extracted​

Symptoms: SQL assets (catalogs, schemas, tables) appear in Atlan, but domains and data products don't.

Possible causes and solutions:

  • Domain filter applied: Check whether specific domains were selected in the crawler configuration.
  • Missing BIAC privileges: If built-in access control is enabled, the Atlan user's role needs SHOW on domains and data products.
  • Data products API unavailable: Verify the data products API is enabled on your Starburst Enterprise instance by testing the endpoint directly: 
    curl -u username:password https://<your-starburst-host>/api/v1/dataProduct/domains

Extraction times out on large catalogs​

Symptoms: The crawler fails with timeout errors for catalogs containing a large number of tables or columns.

Possible causes and solutions:

  • Reduce extraction scope: Use the catalog and schema filters to crawl a subset of schemas at a time, rather than the entire catalog.
  • Check Starburst cluster health: Slow query responses may indicate resource pressure on the Starburst Enterprise coordinator or workers. Monitor cluster performance during extraction.

What happens if Atlan API token lacks Admin privileges?​

Symptoms: The crawler extracts metadata from Starburst Enterprise but some or all Data Products, Data Domains, and source ratings fail to appear in Atlan.

The Atlan API token provided in the credential form is used for several operations during the workflow. The impact of insufficient privileges depends on which operation fails:

OperationImpact of failureSeverity
Asset Import workflows (Data Domain and Data Product publishing)Domains and Data Products aren't published to Atlan. The workflow fails with an error.Hard failure: no data product metadata is published
Data Product updates (linking to parent Data Domains)Data Products are created but not linked to their parent domains. They won't appear in the correct position in the Data Products tree.Partial failure: assets exist but navigation is broken
Data Product and Data Domain search (qualified name lookups)The connector can't resolve parent relationships for Data Products and StarburstDatasets. Cross-asset linking is incomplete.Partial failure: assets exist but relationships are missing
Custom Metadata creation (Starburst Data Product Ratings)Source ratings and rating counts from Starburst Enterprise won't appear on Data Products. An announcement banner is shown on each Data Product instead, indicating that ratings are unavailable.Graceful degradation: all other metadata is unaffected
Badge creationRating badges (color-coded indicators) won't appear on Data Product profiles.Graceful degradation: all other metadata is unaffected

To resolve this, create a new API token using an account with the Admin role and update the credential form with the new token. See Create an Atlan API token for details.

See also​