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. You can’t edit them or assign or change tag values on an object in the Alation UI. Alation doesn’t support syncing tag values from Alation to Databricks Unity Catalog. On catalog pages, the Picker field for a Databricks Unity Catalog tag renders as a dropdown. This is the standard display format for Picker fields in Alation. For Databricks Unity Catalog tags, the dropdown is read-only, and you can’t select a value from it.
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.
Source Tags Not Visible on Catalog Pages¶
Problem¶
Source tags do not appear on catalog pages, in search facets, or on the Custom Fields page, even though the tags are defined and applied in the source system (Snowflake or Databricks Unity Catalog).
Cause¶
The Enable Source Tags feature is not turned on in Admin Settings > Feature Configuration. When this feature is off, Alation does not extract or display source tags.
Solution¶
A Server Admin must turn on the Enable Source Tags feature in Admin Settings > Feature Configuration, and then run metadata extraction on the Snowflake or Databricks Unity Catalog data source. The source tags appear in the catalog after the next extraction. For details, see Enable Unified Source Tags Model.
Values Missing from a Custom Picker Field After Migration¶
Problem¶
After migration, some values that were previously available in an Alation custom Picker field no longer appear as options in the Picker. The values may still be visible on catalog object pages where they were applied, but they cannot be newly assigned to objects.
Cause¶
When a custom Picker field in Alation shares a name with an extracted source tag, the two are merged into a single unified field during migration. After the merge, the allowed values in the unified Picker field are those defined in the source tag. Values that were part of the original Alation Picker field but are not defined in the source tag will no longer appear as options in the Picker.
Values that were already applied to catalog objects before the migration remain visible on those objects but cannot be newly assigned via the Alation UI unless the value is also defined in the source tag.
Solution¶
The following options are available depending on your requirements:
Add the missing values to the source tag. If the values should be available for assignment in Alation, add them to the source tag definition in Snowflake or Databricks Unity Catalog. After the next metadata extraction, the values will appear in the unified Picker field and can be assigned to objects.
Disable the unified source tags model flag and use a distinctly named Alation custom field. Disabling the flag stops the unified behavior and can allow editing of the affected custom Picker fields. However, disabling the flag does not restore values that were removed from the Picker options during migration. If you need to maintain values independently of the source tag, create a new custom Picker field with a name that does not match any source tag name, and manually re-apply the required values to catalog objects.
Important
Disabling the unified source tags model flag does not restore values that were removed from the Picker options during migration. It also does not restore the original custom Picker field configuration. The flag controls whether the unified behavior is active; it does not reverse the migration.
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.