Debugging Reflection Metadata Errors

You will diagnose and resolve common UHT compilation errors by interpreting metadata logs and correcting improper macro usage in your C++ code.

Debugging Reflection Metadata Errors

In this lesson, you will learn how to interpret Unreal Header Tool (UHT) logs to diagnose and fix common metadata errors when using UPROPERTY and UFUNCTION macros.

When you compile your C++ code, the Unreal Header Tool scans your headers to build the reflection system. If you use a macro incorrectly, UHT stops the process and throws an error in your Output Log. These errors often feel cryptic, but they usually point directly to a misuse of "specifiers"—the keywords inside your macro parentheses.

Identifying the Culprit

A common error occurs when you apply a specifier that isn't supported by the macro type. For example, if you try to use BlueprintCallable on a UPROPERTY instead of a UFUNCTION, or pass an invalid argument to a specifier, UHT will trigger a Reflection Metadata Error.

Consider this incorrect snippet:

UPROPERTY(EditAnywhere, BlueprintCallable) // Error: BlueprintCallable is for UFUNCTION!
float MovementSpeed;

When you see a UHT error, look at the line number provided in the log. It is almost always a result of a mismatch between the macro and its arguments. The log usually includes a message like Property 'MovementSpeed' has invalid specifier 'BlueprintCallable'.

Resolving the Conflict

To debug these errors, follow this checklist:

Match the Macro: Ensure BlueprintCallable, BlueprintPure, or Server/Client are used only inside UFUNCTION().
Check the Specifier Syntax: Ensure you are using a comma to separate specifiers (e.g., UPROPERTY(EditAnywhere, BlueprintReadWrite)).
Verify Header Compatibility: Ensure you aren't placing reflection macros inside non-UObject classes or missing the GENERATED_BODY() macro in your class definition. If the UHT doesn't "see" your class as a valid UObject, any metadata attached to it will fail to compile.

Whenever UHT complains, stop looking at your C++ logic and start looking at your header macros. Often, deleting the Intermediate and Binaries folders and re-generating your project files after fixing a syntax error can clear up "ghost" errors caused by cached metadata.

Key Takeaway: Metadata errors are almost always caused by applying function-specific specifiers to properties, or simple syntax mismatches within your U-macro declarations.