What It Means & How to Fix It in UE5

---

🧠 Why You’re Seeing This Error

This error occurs when Unreal Engine is trying to compile a shader permutation, but encounters a macro that it doesn’t recognize or isn’t properly defined.

In UE5, this often means:

• A #define, #if, or #ifdef references a macro that was never defined
• A shader permutation domain (like MATERIAL_SHADINGMODEL_*) is used outside a valid context
• There is a missing include, usually something like Common.ush or MaterialTemplate.ush
• A macro was passed to the compiler via IMPLEMENT_SHADER_TYPE or ShouldCompilePermutation() but is not handled correctly in the .usf file

---

💥 Example Error Message

Error parsing shader permutation: unexpected macro 'USE_CUSTOM_FEATURE'

---

🛠️ Common Shader Scenarios That Trigger This

❌ Referencing Undefined Macros

#if USE_CUSTOM_FEATURE // ❌ Undefined anywhere
    float4 result = CustomLighting();
#endif

---

❌ Using a Material Macro Outside a Valid Material Shader

#if MATERIAL_SHADINGMODEL_SUBSURFACE // ❌ Only works inside Material shaders

---

❌ Forgetting Required Includes That Define Macros

#include "/Engine/Private/Common.ush" // ✅ Defines many global macros
#include "/Engine/Private/MaterialTemplate.ush" // ✅ For material shaders

---

✅ How to Fix Unexpected Macro Errors – Step-by-Step

---

✔️ 1. Make Sure All Macros Are Properly Defined or Wrapped

Before using a macro, define it or guard against it being undefined:

#ifdef USE_CUSTOM_FEATURE
    // Safe logic
#endif

Or use:

#if defined(USE_CUSTOM_FEATURE)

---

✔️ 2. Include All Required Shader Headers

At the top of your .usf or .ush file, include headers that define the macros you’re referencing:

#include "/Engine/Private/Common.ush"
#include "/Engine/Private/MaterialTemplate.ush"

---

✔️ 3. Don’t Use Material-Only Macros in Global or Compute Shaders

If you’re not inside a Material shader, macros like the following will fail:

MATERIAL_SHADINGMODEL_SUBSURFACE
NUM_MATERIAL_OUTPUTS

Avoid them unless you’re in a shader subclass that properly supports them (like FMaterialShader).

---

✔️ 4. Clean Derived Data and Recompile Shaders

Sometimes stale permutation metadata causes macro mismatches.

Delete: DerivedDataCache/
Restart UE5 to recompile shaders fresh

---

✅ Summary: How to Fix “Error Parsing Shader Permutation: Unexpected Macro” in UE5

Cause	Fix
Using undefined macro in .usf file	Wrap in #ifdef, or define macro manually
Shader header didn’t include macros	Add #include "/Engine/Private/Common.ush"
Used material-only macro in global shader	Move logic or rewrite using general-purpose macros
Bad permutation logic in C++	Check ShouldCompilePermutation() for macro assumptions