Tag Associations Visible on Assets But Missing from Tag Picker: Emitting Tag Entities vs. Associations – DataHub Customer Support Portal

Area: Ingestion Issues

Sub-Area: Tag Entity Registration and Ingestion Configuration

Issue

Tags applied to assets (such as dataset columns) appear correctly on the asset detail view but do not show up in the "Manage Tags" tab, tag pickers, or tag dropdowns elsewhere in the DataHub UI. This occurs because the ingestion pipeline emits only the tag association (i.e., the reference linking a tag URN to an asset) without also emitting the tag entity itself. DataHub stores these as separate constructs: a GlobalTagsAspect on an asset records which tag URNs are associated with it, but the tag entity — which requires at minimum a TagProperties aspect — must be independently created and indexed before the tag is recognized as a first-class, manageable object in the platform.

Error Messages

Tag visible on asset column but absent from Manage Tags tab and tag picker dropdowns

You Might Be Asking

Why does a tag appear on my dataset column but not show up when I search for it in the tag picker?
Why is a tag missing from the "Manage Tags" governance tab even though it is applied to an asset?
How do I register a tag as a proper entity in DataHub so it appears in all UI surfaces?
What is the difference between a tag association and a tag entity in DataHub?

Solution

Choose one of the following approaches to register the tag as a proper entity so it appears in tag pickers, the "Manage Tags" tab, and all other governance surfaces.

Option 1: Register the Tag via the UI (Quickest Fix)

Navigate to any asset where the tag is currently applied and locate the tag on the asset's detail page.
Click directly on the tag label. This opens the tag's detail page at a URL such as https://<your-instance>.acryl.io/tag/urn:li:tag:<your-tag-urn>.
Click Edit and add at minimum a display name or description for the tag.
Click Save. DataHub will now index the tag as a proper entity, and it will appear in the "Manage Tags" tab and all tag pickers.

Option 2: Emit the Tag Entity from Your Ingestion Pipeline

Update your ingestion code to emit a MetadataChangeProposal for the tag entity in addition to any tag associations. The tag entity requires at least a TagProperties aspect.

from datahub.emitter.mcp import MetadataChangeProposalWrapper
from datahub.metadata.schema_classes import TagPropertiesClass
from datahub.emitter.rest_emitter import DatahubRestEmitter

tag_urn = "urn:li:tag:<your-tag-name>"

tag_entity_mcp = MetadataChangeProposalWrapper(
    entityUrn=tag_urn,
    aspect=TagPropertiesClass(
        name="<Your Tag Display Name>",
        description="<Optional description of the tag>"
    ),
)

emitter = DatahubRestEmitter(gms_server="https://<your-datahub-host>:8080")
emitter.emit(tag_entity_mcp)

Ensure this emission happens before or alongside any aspect that applies the tag association to an asset.

Option 3: Create the Tag Entity via the REST API

curl -X POST "https://<your-datahub-host>:8080/aspects?action=ingestProposal" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-token>" \
  -d '{
    "proposal": {
      "entityType": "tag",
      "entityUrn": "urn:li:tag:<your-tag-name>",
      "aspectName": "tagProperties",
      "changeType": "UPSERT",
      "aspect": {
        "contentType": "application/json",
        "value": "{\"name\": \"<Your Tag Display Name>\", \"description\": \"<Optional description>\"}"
      }
    }
  }'

Option 4: Verify and Prevent Soft-Deletion by Ingestion Pipelines

If tags were previously registered but are now missing, they may have been soft-deleted by a pipeline run with remove_stale_metadata: true. Review your source connector stateful ingestion configuration:

source:
  type: <your-source-type>
  config:
    stateful_ingestion:
      enabled: true
      remove_stale_metadata: true  # This can soft-delete tag entities between runs

If tag entities are being deleted between runs, either ensure the pipeline also re-emits tag entities on every run, or manage tags independently of the main ingestion pipeline so they are not subject to stale metadata removal.

Additional Notes

This is a distinction in DataHub's data model: a tag association (stored in GlobalTagsAspect on an asset) and a tag entity (requiring at minimum a TagProperties aspect) are separate constructs. Both must exist for the tag to be fully functional across all UI surfaces.
The "Manage Tags" tab and tag picker dropdowns only surface tags that exist as indexed tag entities. Orphaned tag references (associations without a corresponding entity) will appear on the asset but nowhere else.
If you have a large number of orphaned tag associations, bulk-register the tag entities using the Python SDK emitter in a loop or via the REST API, iterating over all affected tag URNs.
In DataHub Cloud (managed deployments), if tags have been soft-deleted and need to be restored at the infrastructure level (e.g., reindex required), contact DataHub Support and provide the affected tag URNs.
After registering tag entities, allow a short period for the search index to update before verifying appearance in the "Manage Tags" tab.