Photo by Anton Tseiko on Unsplash

It was 11:45pm and the build was supposed to go out the next morning. I hit the build button in Unity, grabbed a coffee, came back, and there it was — a wall of red text and a failed IL2CPP compilation. I'd seen this before. I knew it was going to be one of those nights. If you've shipped anything with Unity targeting Android or iOS, you've probably been here too.

The thing that makes IL2CPP errors genuinely brutal is that the error output is almost deliberately unhelpful. You get a stack of C++ compiler garbage pointing at auto-generated files you've never touched and never should have to touch. Unity converted your C# into C++ behind the scenes, something went wrong in that process, and now you're staring at a cryptic message about a type that doesn't exist or a method that couldn't be stripped. Fun times.

I've fixed this enough times now that I've started keeping notes. Here's what actually works.

What the Error Looks Like

The exact message varies, but you'll usually see something like one of these in your Unity console or build log:

Error: Unity.IL2CPP.Building.BuilderFailedException: C++ code generation failed
...
Internal build system error. BuildProgram exited with code 1.

or

TypeLoadException: Could not load type 'System.SomeType' from assembly '...'

or from Android specifically:

FAILURE: Build failed with an exception.
> Task :launcher:externalNativeBuildRelease FAILED
...
error: use of undeclared identifier 'il2cpp_object_new'

And in the Editor log (which you should always check — Help > Open Editor Log), you'll find something way down in the noise like:

IL2CPP error for method 'System.Void SomeNamespace.SomeClass::SomeMethod()'
System.NotSupportedException: IL2CPP does not support marshaling delegates

That last one is actually useful. Most of the time the real error is buried. Always dig into the full log.

Photo by Tijs van Leur on Unsplash

Why This Happens

IL2CPP is Unity's ahead-of-time compiler. Instead of shipping Mono bytecode, it converts your C# into C++, then compiles that with a native compiler for the target platform. The benefit is performance and security. The downside is that a ton of things that work fine in Mono or Play mode just quietly explode during IL2CPP builds.

The most common reasons I've run into:

• Managed code stripping is too aggressive and removes something a plugin needs at runtime
• A third-party plugin uses reflection or dynamic code generation that IL2CPP can't handle
• Your NDK or build tool version is wrong or missing entirely
• A type or method is genuinely unsupported under IL2CPP (some .NET APIs just aren't)

Fix 1: Check Your NDK and SDK Setup First

Honestly, this is the one that trips people up the most and feels the most embarrassing because the fix takes 30 seconds. If you're building for Android, your NDK version matters a lot.

Go to Edit > Preferences > External Tools and check what NDK path Unity is pointing at. If it's blank, or pointing at a path that no longer exists, you'll get nonsense IL2CPP errors that look like code problems but aren't.

For Unity 2021+, the recommended approach is to let Unity manage the NDK for you:

// In Unity Hub
// Go to your Unity version > Add Modules > Android Build Support
// Make sure "Android NDK & SDK Tools" is checked and installed

If you're managing it manually, Unity 2021 LTS wants NDK r21d or r23b depending on your exact version. Check the Unity docs for your specific release — this is one of those places where using the wrong version by one letter actually matters.

Fix 2: Adjust Managed Stripping Level

This one fixes a huge percentage of IL2CPP build failures that involve missing types or methods, especially with third-party SDKs.

Go to Edit > Project Settings > Player > Other Settings and find Managed Stripping Level. Drop it down. If it's on High, try Medium. If it's on Medium, try Low. If it's on Low and you're still hitting this, try Minimal.

Look, I know that's not a surgical fix. But it'll tell you instantly whether stripping is the culprit. If your build succeeds after lowering it, you then need to add a link.xml file to preserve the specific types that were being stripped:

<!-- Assets/link.xml -->
<linker>
  <assembly fullname="SomePluginAssembly" preserve="all"/>
  <assembly fullname="System.Core">
    <type fullname="System.Linq.Expressions.Interpreter.LightLambda" preserve="all"/>
  </assembly>
</linker>

The assembly name you need to preserve will be in that buried error message I mentioned earlier. Copy it exactly.

Fix 3: Track Down the Unsupported Plugin Code

Sometimes the problem is a specific plugin using something IL2CPP genuinely can't compile. Reflection.Emit is the classic one. Dynamic code generation. Certain delegate marshaling patterns. These work in the editor, work in Mono builds, and then completely fall apart under IL2CPP.

Your best move here is to search the full Editor log for the method name in the error, then trace it back to which plugin owns that assembly. Once you know the plugin, check if there's an IL2CPP-compatible version available. Most major SDK vendors (Firebase, Adjust, etc.) have dealt with this and have updated their packages.

If you're stuck on an old plugin version and can't upgrade, add a scripting define and wrap the problematic code:

#if !ENABLE_IL2CPP
    // code that only runs under Mono
    dynamicMethod.Invoke(...);
#else
    // IL2CPP-safe fallback
#endif

Not pretty. But it works when you're under deadline and can't refactor the whole thing.

If None of That Worked

Delete your Library folder. I'm serious. It's a cache, Unity will rebuild it, and it fixes a genuinely surprising number of IL2CPP weirdness that seems completely unrelated to caching. Close Unity, delete the folder, reopen, rebuild. Painful to wait through, but I've saved myself hours of debugging by doing this first.

# From your project root
rm -rf Library/

Also — and I can't stress this enough — look at the very bottom of the Editor log, not the console. The console shows you a summary. The log shows you everything. The actual root cause error is almost always a few hundred lines above the final "build failed" line.

You'll Get Through It

IL2CPP errors are one of those things that feel impossible the first few times and then become pretty predictable once you've seen the patterns. Ninety percent of the time it's the NDK, the stripping level, or a plugin that predates IL2CPP support. The remaining ten percent is genuinely weird, and for that you've got the Unity forums and a fresh Library folder.

Check your logs, drop the stripping level first to confirm the diagnosis, then be surgical about what you preserve. And maybe don't schedule IL2CPP build debugging for midnight before a release. Not that I've made that mistake repeatedly or anything.