Unity-Technologies/UnityCsReference · error · InvalidOperationException

IL2CPP doesn't support building with {apiCompatibilityLevel}

Error message

IL2CPP doesn't support building with {apiCompatibilityLevel} API compatibility level!

What it means

Thrown inside the switch that selects IL2CPP #defines for a given ApiCompatibilityLevel. Only NET_Unity_4_8, NET_Standard, and the deprecated NET case are handled; any other compatibility level falls through to default and throws InvalidOperationException, because IL2CPP has no defined base #define set for that level.

Source

Thrown at Editor/Mono/BuildPipeline/Il2Cpp/IL2CPPUtils.cs:464

        }

        internal static string[] GetBuilderDefinedDefines(BuildTarget target, ApiCompatibilityLevel apiCompatibilityLevel, bool enableIl2CppDebugger)
        {
            List<string> defines = new List<string>();

            switch (apiCompatibilityLevel)
            {
                case ApiCompatibilityLevel.NET_Unity_4_8:
                case ApiCompatibilityLevel.NET_Standard:
                    // CORECLR_FIXME - .NET Should have a different set of defines
#pragma warning disable CS0618
                case ApiCompatibilityLevel.NET:
#pragma warning restore CS0618
                    defines.AddRange(BaseDefines46);
                    break;

                default:
                    throw new InvalidOperationException($"IL2CPP doesn't support building with {apiCompatibilityLevel} API compatibility level!");
            }

            if (target == BuildTarget.StandaloneWindows || target == BuildTarget.StandaloneWindows64 ||
                target == BuildTarget.XboxOne || target == BuildTarget.WSAPlayer)
            {
                defines.AddRange(BaseDefinesWindows);

                if (target == BuildTarget.WSAPlayer)
                {
                    defines.Add("WINAPI_FAMILY=WINAPI_FAMILY_APP");
                }
                else
                {
                    defines.Add("WINAPI_FAMILY=WINAPI_FAMILY_DESKTOP_APP");
                }
            }

            if (enableIl2CppDebugger)

View on GitHub (pinned to 225b0fbdb5)

Solutions

Switch Player Settings > Api Compatibility Level to '.NET Standard 2.1' or '.NET Framework 4.x' (NET_Unity_4_8), both supported by IL2CPP.
Validate the compatibility level against the supported set before invoking the IL2CPP define builder.
If scripting a custom build, normalize the level to NET_Standard or NET_Unity_4_8 explicitly.

Example fix

// before
var defines = GetBuilderDefinedDefines(target, apiCompatibilityLevel, enableDebugger);

// after
var supported = apiCompatibilityLevel == ApiCompatibilityLevel.NET_Standard
             || apiCompatibilityLevel == ApiCompatibilityLevel.NET_Unity_4_8;
if (!supported) throw new InvalidOperationException("Switch API Compatibility Level to .NET Standard or .NET 4.x before building IL2CPP.");
var defines = GetBuilderDefinedDefines(target, apiCompatibilityLevel, enableDebugger);

Defensive patterns

Strategy: validation

Validate before calling

static readonly HashSet<ApiCompatibilityLevel> Il2CppSupported = new()
{
    ApiCompatibilityLevel.NET_Unity_4_8,
    ApiCompatibilityLevel.NET_Standard,
#pragma warning disable CS0618
    ApiCompatibilityLevel.NET
#pragma warning restore CS0618
};
if (!Il2CppSupported.Contains(apiCompatibilityLevel))
    throw new InvalidOperationException("Set API Compatibility Level to .NET Standard or .NET 4.x for IL2CPP.");

Type guard

static bool IsIl2CppSupported(ApiCompatibilityLevel l) =>
    l == ApiCompatibilityLevel.NET_Unity_4_8 ||
    l == ApiCompatibilityLevel.NET_Standard ||
#pragma warning disable CS0618
    l == ApiCompatibilityLevel.NET;

Prevention

Before invoking IL2CPP define generation, verify the compatibility level is in the supported set.
Standardize project Player Settings to .NET Standard 2.1 for IL2CPP builds.

When it happens

Trigger: Calling the IL2CPP define-builder (GetBuilderDefinedDefines) with an ApiCompatibilityLevel outside the supported set, e.g. NET_2_0, NET_2_0_Subset, NET_Web, or a custom/legacy level, while targeting an IL2CPP backend.

Common situations: A project migrated from an old Mono/.NET 2.0 Subset setup that retains a legacy ApiCompatibilityLevel after switching the backend to IL2CPP; programmatic define generation invoked with an enum value no longer supported by IL2CPP.

Related errors

AI-assisted analysis of Unity-Technologies/UnityCsReference@225b0fbdb5 (2026-08-13). Data as JSON: /api/errors/20ba2aba8325986a. Report an issue: GitHub.