Troubleshoot Unified Source Tags Model¶
Alation Cloud Service Applies to Alation Cloud Service instances of Alation
Customer Managed Applies to customer-managed instances of Alation
Applies from Alation version 2025.1.3
Certain behavior and error scenarios may be connected to the current limitations of the unified tag extraction framework.
In this topic:
Limitations of the Unified Source Tags Model¶
These limitations apply to the Alation version 2025.1.3 of the unified tag extraction framework. Some limitations may evolve in future releases.
Limitations in the Unification Model¶
Built-in Picker fields, such as status and revision status, are excluded from unification. This means, if there’s a source tag with the same name as these built-in Picker fields (Status and Revision Status), the tag won’t be unified with them and a separate custom field will be created still resulting in duplicate Pickers.
The unified source tags model is not applicable to Multi-Select Picker fields. Therefore, if there’s a source tag with the same name which is present in the Multi-Select Picker field, the tag won’t be unified resulting in duplicate entries in the Picker and Multi-Select Picker section in Alation.
When Alation merges multiple fields with the same name into a single unified field (for example, during migration), it preserves only the history associated with the retained field. Alation does not retain the histories of other merged fields.
In the catalog page’s history view, tags are displayed in an internal format using IDs and separators, instead of user-friendly, human-readable values.
Alation does not automatically resolve semantic equivalence between values (for example, In Review vs Reviewing). You can manually align such values.
Limitations in Databricks Unity Catalog Tags¶
Databricks Unity Catalog tags are read-only by design and cannot be edited and users cannot assign or change the tag value on an object in the Alation UI. There is no support to sync tag values from Alation to Databricks Unity Catalog.
Limitations in Custom Fields¶
Custom fields defined in Alation with the same name but different intended usage are merged by name, without distinction.
If two Alation-defined custom fields have the same name (for example,
Department) but are intended for different governance purposes, Alation merges them by name but does not resolve their meaning.Alation allows creating custom fields with identical names and values. Users can still create custom fields with the same names as the Picker fields created automatically during tag extraction. In this sense, the unified source tag model doesn’t completely remove duplicate fields. For example, textually identical or semantic values such as In Review and Reviewing.
Duplicate fields may persist after migration or after the first metadata extraction due to prior inconsistencies or non-normalized fields. However, this is very rare. You can correct them through manual field cleanup.
Limitations in Deletion of Source Tags¶
Alation doesn’t support partial deletion (deleting tag definitions but not its tag links). This means that links are not retained if the parent definition is removed.
Alation doesn’t provide a UI preview or warning showing where a tag is used across schemas or systems before deletion.
Tag deletion controls are implemented on a per-connector basis and are not centrally managed. Consequently, a universal setting for tag deletion across all data sources does not exist; each connector requires individual configuration.
Troubleshoot the Unified Source Tags Model¶
Refer to the following scenarios for help in troubleshooting common issues.
Migration¶
Problem¶
After migration Alation displays tags belonging to custom fields for which users did not have required permissions.
Cause¶
Migration unifies tags with the same name and also merges the permissions.
Solution¶
Catalog Admin should check for existing permissions on the unified custom fields from the Custom Fields Permission page and edit them as required.
Problem¶
Duplicate custom fields are displayed on the Customize Catalog page and on the objects catalog page.
Cause¶
It may happen due to the following reasons:
The unified tags feature is not enabled or migration hasn’t been run.
Tags with the same name might belong to different schemas in Snowflake and these tags are also applied to given objects. Alation creates separate custom fields when tag definitions are structurally incompatible (for example, allowed values differ) even if the tag names are the same.
Solution¶
On the catalog page, Catalog users can use the field label tooltip to check the schema or source of each field. If duplicate fields are not desired, Admins may choose to align tag definitions in the source or adjust template configuration.
Problem¶
Unified custom fields are not appearing at the place where the earlier custom fields appeared in catalog page or on the Customize Catalog template page.
Cause¶
By default, Alation places the unified custom field at the top of the right-hand column of the page after migration.
Solution¶
On the catalog page or Customize Catalog page, you can edit the template to move the unified custom field to the desired location.
Metadata Extraction¶
Problem¶
Tags aren’t displayed in the catalog page after metadata extraction.
Cause¶
Custom fields belonging to tags are not added to the template.
Solution¶
The Catalog Admin or Server Admin must add corresponding custom fields to respective templates. For more information, see the Add Source Tags to Templates section in Bring Source Tags into Alation.
Problem¶
Unable to run a downstream job after metadata extraction
Cause¶
The feature flag (alation.feature_flags.DEV_enable_unified_tags) for unified source tags is not enabled.