Why does my FGameplayTag comparison return false even though the tags look identical?

The most common cause is that one of the tags is not registered in your project's GameplayTags settings. An unregistered tag created via FGameplayTag::RequestGameplayTag with ErrorIfNotFound set to false silently creates an invalid tag that never matches anything. Always check IsValid() on your tags before comparing them.

How do I query a FGameplayTagContainer for multiple tags at once?

Use HasAll to check if the container has every tag in a set, or HasAny to check if it has at least one. Both methods accept an FGameplayTagContainer as the parameter. For more complex queries, use FGameplayTagQuery which supports nested AND, OR, and NOT expressions built through FGameplayTagQueryExpression.

Fix: Unreal Engine Gameplay Tag Not Matching Tag Query

Quick answer: HasTag performs hierarchical matching. If a container has the tag 'Damage.Fire.DOT', calling HasTag with 'Damage.Fire' returns true because 'Damage.Fire' is a parent of 'Damage.Fire.DOT'. HasTagExact requires the exact tag to be present. The same check with HasTagExact('Damage.

Here is how to fix Unreal gameplay tag not matching query. You compare two Gameplay Tags in Unreal Engine and the match fails even though the tags appear to be the same. Your ability system does not activate, your damage filter ignores the right damage type, or your tag query returns false when you expect true. This is almost always caused by confusion between hierarchical matching and exact matching, unregistered tags that silently fail, or incorrect FGameplayTagQuery construction.

How Gameplay Tag Matching Works

Gameplay Tags in Unreal Engine are hierarchical. A tag like Status.Debuff.Stun has implicit parent tags: Status.Debuff and Status. When you use hierarchical matching (the default), checking if a container has Status.Debuff returns true if the container holds Status.Debuff.Stun, because the child tag implies its parents.

This hierarchical behavior is the source of most confusion. Developers expect exact string comparison but get hierarchy-aware comparison instead, or they expect hierarchical matching but use an exact-match function.

HasTag vs HasTagExact

The FGameplayTagContainer class provides two primary matching methods that behave very differently.

HasTag performs hierarchical matching. If the container holds Damage.Fire.DOT and you call HasTag(Damage.Fire), it returns true because Damage.Fire is a parent of Damage.Fire.DOT.

HasTagExact requires the exact tag to be present. The same call with HasTagExact(Damage.Fire) returns false because only Damage.Fire.DOT is in the container, not Damage.Fire itself.

// Demonstrate the difference between HasTag and HasTagExact
void AMyActor::TestTagMatching()
{
    FGameplayTagContainer Container;
    Container.AddTag(
        FGameplayTag::RequestGameplayTag(FName("Damage.Fire.DOT"))
    );

    FGameplayTag ParentTag = FGameplayTag::RequestGameplayTag(FName("Damage.Fire"));
    FGameplayTag ExactTag = FGameplayTag::RequestGameplayTag(FName("Damage.Fire.DOT"));

    // Hierarchical match: true (DOT is a child of Fire)
    bool bHasParent = Container.HasTag(ParentTag);
    UE_LOG(LogTemp, Log, TEXT("HasTag(Damage.Fire) = %s"),
        bHasParent ? TEXT("true") : TEXT("false"));

    // Exact match: false (container has DOT, not Fire itself)
    bool bHasParentExact = Container.HasTagExact(ParentTag);
    UE_LOG(LogTemp, Log, TEXT("HasTagExact(Damage.Fire) = %s"),
        bHasParentExact ? TEXT("true") : TEXT("false"));

    // Exact match: true (exact tag is present)
    bool bHasExact = Container.HasTagExact(ExactTag);
    UE_LOG(LogTemp, Log, TEXT("HasTagExact(Damage.Fire.DOT) = %s"),
        bHasExact ? TEXT("true") : TEXT("false"));
}

Choose the right function for your use case. If you want to check "is this any kind of fire damage," use HasTag with Damage.Fire. If you want to check "is this specifically fire DOT damage," use HasTagExact with Damage.Fire.DOT.

Unregistered Tags Silently Fail

When you call FGameplayTag::RequestGameplayTag with a tag name that is not registered in your project's Gameplay Tags list, the behavior depends on the ErrorIfNotFound parameter. If set to false (or omitted in some contexts), the function returns an empty, invalid FGameplayTag that matches nothing.

// Always validate tags after requesting them
void AMyActor::SafeTagCheck()
{
    FGameplayTag Tag = FGameplayTag::RequestGameplayTag(
        FName("Status.Debuff.Stun"), /* ErrorIfNotFound */ false
    );

    if (!Tag.IsValid())
    {
        UE_LOG(LogTemp, Error,
            TEXT("Tag 'Status.Debuff.Stun' is not registered! "
                 "Add it in Project Settings > Gameplay Tags."));
        return;
    }

    // Tag is valid, safe to use in comparisons
    UE_LOG(LogTemp, Log, TEXT("Tag is valid: %s"), *Tag.ToString());
}

A typo in the tag name is the most common cause. Damage.fire.DOT versus Damage.Fire.DOT looks similar but they are different tags. Gameplay Tags are case-sensitive in their FName representation. Always copy tag names from the Gameplay Tags editor rather than typing them manually in code.

FGameplayTagQuery for Complex Matching

Simple HasTag and HasAny/HasAll cover most cases. But when you need complex boolean logic such as "has fire damage AND is a DOT but NOT if the target has fire immunity," use FGameplayTagQuery.

// Build a complex tag query
void AMyActor::ComplexTagQuery()
{
    // Query: must have Damage.Fire AND Status.Debuff, must NOT have Immunity.Fire
    FGameplayTagQuery Query = FGameplayTagQuery::BuildQuery(
        FGameplayTagQueryExpression()
            .AllExprMatch()
            .AddExpr(
                FGameplayTagQueryExpression()
                    .AllTagsMatch()
                    .AddTag(FGameplayTag::RequestGameplayTag(FName("Damage.Fire")))
                    .AddTag(FGameplayTag::RequestGameplayTag(FName("Status.Debuff")))
            )
            .AddExpr(
                FGameplayTagQueryExpression()
                    .NoTagsMatch()
                    .AddTag(FGameplayTag::RequestGameplayTag(FName("Immunity.Fire")))
            )
    );

    FGameplayTagContainer TargetTags;
    TargetTags.AddTag(FGameplayTag::RequestGameplayTag(FName("Damage.Fire.DOT")));
    TargetTags.AddTag(FGameplayTag::RequestGameplayTag(FName("Status.Debuff.Stun")));

    bool bMatches = Query.Matches(TargetTags);
    UE_LOG(LogTemp, Log, TEXT("Complex query result: %s"),
        bMatches ? TEXT("true") : TEXT("false"));
}

The key detail with FGameplayTagQuery is that it uses hierarchical matching by default in its AllTagsMatch and AnyTagsMatch expressions. Querying for Damage.Fire will match a container that has Damage.Fire.DOT. There is no built-in exact-match variant for queries, so if you need exact matching inside a query, you must match the full tag path.

HasAll and HasAny Container Methods

When checking multiple tags at once, use HasAll or HasAny on the container instead of calling HasTag in a loop.

// Check for multiple tags efficiently
void AMyActor::MultiTagCheck(const FGameplayTagContainer& TargetTags)
{
    FGameplayTagContainer RequiredTags;
    RequiredTags.AddTag(FGameplayTag::RequestGameplayTag(FName("Status.Alive")));
    RequiredTags.AddTag(FGameplayTag::RequestGameplayTag(FName("Team.Player")));

    // HasAll: target must have EVERY tag (hierarchical)
    if (TargetTags.HasAll(RequiredTags))
    {
        UE_LOG(LogTemp, Log, TEXT("Target has all required tags"));
    }

    FGameplayTagContainer AnyOfThese;
    AnyOfThese.AddTag(FGameplayTag::RequestGameplayTag(FName("Damage.Fire")));
    AnyOfThese.AddTag(FGameplayTag::RequestGameplayTag(FName("Damage.Ice")));

    // HasAny: target must have AT LEAST ONE tag (hierarchical)
    if (TargetTags.HasAny(AnyOfThese))
    {
        UE_LOG(LogTemp, Log, TEXT("Target has elemental damage"));
    }
}

Both HasAll and HasAny perform hierarchical matching. Their exact-match counterparts are HasAllExact and HasAnyExact. Using the wrong variant is a common source of "tag not matching" bugs.

Related Issues

If your Gameplay Ability System abilities are not activating despite correct tags, check the ability's Activation Required Tags and Activation Blocked Tags in the ability CDO. If tags work in editor but not in packaged builds, ensure your GameplayTags .ini files are included in the packaging settings. For Blueprint tag comparisons, use the Match Tag node and verify the Match Type pin is set correctly.

Always call IsValid() on tags from RequestGameplayTag. An invalid tag silently fails every comparison and you will spend hours wondering why.