Fix: Unreal Gameplay Tag Missing From Ini File

Here is how to fix Unreal gameplay tags that exist in code but never match at runtime. You set up a GameplayAbility that grants State.Buffed.Speed, an enemy AI that checks for State.Buffed.Speed, and the check always returns false. The tag is referenced everywhere. It still does not resolve.

The Symptom

You have defined a gameplay tag hierarchy for your game — damage types, states, abilities, targeting filters. You wrote code that adds and queries these tags on characters via the Gameplay Ability System. Everything compiles. At runtime, HasTag returns false for tags that were just granted, FindChildTags comes back empty, and Blueprint nodes that compare tags evaluate to false even when both sides look identical.

You print the tag from the granted container and from the query container. They print identical strings. And yet they do not match. Sometimes, in the output log you see a line like LogGameplayTags: Warning: Requested gameplay tag State.Buffed.Speed was not found. Other times there is no warning at all, just silent failure.

Even more confusing: the tag shows up in the tag picker in Blueprint after a restart. It appears to exist. But calling FGameplayTag::RequestGameplayTag("State.Buffed.Speed") returns an invalid tag.

What Causes This

Unreal gameplay tags are not strings. They are FName-backed handles resolved against a global registry called UGameplayTagsManager. The manager loads tags from three sources at startup:

• Native declarations via UE_DEFINE_GAMEPLAY_TAG macros in C++ modules
• Config files, primarily Config/DefaultGameplayTags.ini and any referenced tag list files
• Data tables assigned in the Project Settings → Gameplay Tags section

If a tag is not present in any of those three sources, the manager does not know about it. Asking for it by string returns an invalid FGameplayTag, which compares unequal to every other tag — even to another invalid tag created from the same string.

The common failure: someone types the tag into a UPROPERTY with a Categories meta specifier, assigns a value from the editor picker, and assumes the tag is “registered” simply because the editor accepted it. But the picker also allows creating new tags on the fly, which writes them to a transient source. If the transient save does not land in DefaultGameplayTags.ini (perhaps because the ini was read-only or source controlled without checkout), the tag exists in the asset that references it but not in the global registry.

A second failure mode: a C++ module uses UE_DEFINE_GAMEPLAY_TAG to register a tag, but the module is not loaded until after the game starts — for instance, a gameplay plugin that loads only when a specific level streams in. Any code that references the tag before the module loads sees it as unregistered.

The Fix

Step 1: Define tags natively when they are used in C++. Create a dedicated header and cpp pair for your game’s tags:

// MyGameGameplayTags.h
#pragma once
#include "NativeGameplayTags.h"

namespace MyGameTags
{
  UE_DECLARE_GAMEPLAY_TAG_EXTERN(State_Buffed_Speed);
  UE_DECLARE_GAMEPLAY_TAG_EXTERN(State_Debuffed_Slow);
  UE_DECLARE_GAMEPLAY_TAG_EXTERN(Event_Ability_Activated);
}

// MyGameGameplayTags.cpp
#include "MyGameGameplayTags.h"

namespace MyGameTags
{
  UE_DEFINE_GAMEPLAY_TAG(State_Buffed_Speed, "State.Buffed.Speed");
  UE_DEFINE_GAMEPLAY_TAG(State_Debuffed_Slow, "State.Debuffed.Slow");
  UE_DEFINE_GAMEPLAY_TAG(Event_Ability_Activated, "Event.Ability.Activated");
}

Now reference them by symbol rather than string:

if (AbilitySystemComponent->HasMatchingGameplayTag(MyGameTags::State_Buffed_Speed))
{
  // Safe — symbol is compiler-checked and registered at module startup
}

Step 2: Add the tag to DefaultGameplayTags.ini as a backup and for Blueprint discoverability. Open Config/DefaultGameplayTags.ini:

; Config/DefaultGameplayTags.ini
[/Script/GameplayTags.GameplayTagsSettings]
+GameplayTagList=(Tag="State.Buffed.Speed",DevComment="Increased movement speed buff")
+GameplayTagList=(Tag="State.Debuffed.Slow",DevComment="Reduced movement speed debuff")
+GameplayTagList=(Tag="Event.Ability.Activated",DevComment="Fired when any ability activates")

If the tag is defined both natively and in the ini, Unreal merges the two — the native definition wins, the ini entry serves as documentation and editor-only fallback.

Step 3: For UPROPERTY tag pickers, set Categories correctly. When exposing a tag property to Blueprint, use the Categories meta to restrict the picker to the right subtree:

UPROPERTY(EditAnywhere, BlueprintReadOnly, meta=(Categories="State.Buffed"))
FGameplayTag RequiredBuff;

This prevents designers from typing a brand-new tag that will not exist at runtime.

Step 4: If you renamed a tag, add a redirector. Deleting a tag breaks every Blueprint and data asset referencing it. Instead, add a redirect:

[/Script/GameplayTags.GameplayTagsSettings]
+GameplayTagRedirects=(OldTagName="State.Buff.Speed",NewTagName="State.Buffed.Speed")

Unreal transparently remaps references on load. After every asset touching the old tag has been re-saved, you can remove the redirector.

Enable LogGameplayTags at Verbose via -LogCmds="LogGameplayTags Verbose" on the command line to see every tag registration and lookup attempt. Invalid tag resolutions print a warning that is otherwise easy to miss.

Why This Works

Defining a tag natively guarantees it is registered when the module loads — long before any gameplay code runs. Because the macro creates a static FGameplayTag, you get compile-time symbol checking: renaming in one place forces a recompile of every call site. This is much safer than string-based lookup.

Keeping a mirrored entry in DefaultGameplayTags.ini makes the tag visible in editor pickers even in projects where the native module has not yet been loaded, and gives designers a documentation comment. Redirectors let you evolve the tag hierarchy without breaking asset references.

Related Issues

For Gameplay Abilities that fail to activate despite matching tag requirements, see Fix: Unreal Gameplay Ability Not Activating — tag mismatches and blocking tags are usually the cause.

If your DefaultGameplayTags.ini changes are not being picked up in packaged builds, see Fix: Unreal Config Changes Not Included in Packaged Build.

Native tags for C++ code. Ini entries for Blueprint pickers. Redirectors for renames. Never type a tag as a raw string.