Unity-Technologies/UnityCsReference · error · ArgumentException

Unhandled scripting backend {scriptingBackend}

Error message

Unhandled scripting backend {scriptingBackend}

What it means

Thrown by ApiCompatibilityLevelToDotNetProfileArgument when the scripting backend is none of Mono, IL2CPP, or CoreCLR. This is a defensive exhaustiveness check: the method handles exactly three backend branches and throws ArgumentException for anything else, indicating an unhandled or newly introduced ScriptingBackend enum value.

Source

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

                        return "unityaot-" + BuildTargetDiscovery.GetPlatformProfileSuffix(target);
#pragma warning disable CS0618
                    case ApiCompatibilityLevel.NET:
#pragma warning restore CS0618
                        // We won't need the profile argument going forward.  Dropping this option also acts as an indicator to il2cpp to use the new bcl.
                        return null;

                    default:
                        throw new NotSupportedException(string.Format("ApiCompatibilityLevel.{0} is not supported!", compatibilityLevel));
                }
            }

            if (scriptingBackend == ScriptingBackend.CoreCLR)
            {
                // We won't need the profile argument going forward
                return null;
            }

            throw new ArgumentException($"Unhandled scripting backend {scriptingBackend}");
        }

        internal static List<string> GetIL2CPPReferenceDirectories(BuildTarget target, NamedBuildTarget namedTarget,
            BuildOptions buildOptions, ApiCompatibilityLevel apiCompatibilityLevel)
        {
            var result = new List<string>();
#pragma warning disable CS0618
            if (apiCompatibilityLevel != ApiCompatibilityLevel.NET)
#pragma warning restore CS0618
            {
                result.Add(BCLExtensions.NetstandardRuntimeDirectory());
                var profileDirectory = MonoInstallationFinder.GetProfileDirectory(
                    BuildPipeline.CompatibilityProfileToClassLibFolder(ApiCompatibilityLevel.NET_Standard),
                    MonoInstallationFinder.MonoBleedingEdgeInstallation);
                result.Add(profileDirectory);
                result.Add(Path.Combine(profileDirectory, "Facades"));
                return result;
            }

View on GitHub (pinned to 225b0fbdb5)

Solutions

1. Set PlayerSettings.SetScriptingBackend to ScriptingBackend.IL2CPP, ScriptingBackend.Mono, or ScriptingBackend.CoreCLR.
2. Repair ProjectSettings.scriptingBackend in ProjectSettings.asset to a valid value (0 = IL2CPP, 1 = Mono, 3 = CoreCLR in most Unity versions).
3. After a Unity upgrade, verify the ScriptingBackend enum hasn't gained new values that require updated bindings.

Example fix

// before
PlayerSettings.SetScriptingBackend(BuildTargetGroup.Standalone, (ScriptingBackend)42);
// build throws 'Unhandled scripting backend'

// after
PlayerSettings.SetScriptingBackend(BuildTargetGroup.Standalone, ScriptingBackend.IL2CPP);

static readonly HashSet<ScriptingBackend> s_validBackends = new()
{
    ScriptingBackend.IL2CPP,
    ScriptingBackend.Mono,
    ScriptingBackend.CoreCLR
};

void ValidateScriptingBackend(ScriptingBackend backend)
{
    if (!s_validBackends.Contains(backend))
        throw new ArgumentException(
            $"ScriptingBackend.{backend} is not handled by this Unity version. " +
            "Use IL2CPP, Mono, or CoreCLR.");
}

// Before building:
ValidateScriptingBackend(
    PlayerSettings.GetScriptingBackend(BuildTargetGroup.Standalone));

When it happens

Trigger: Building with a ScriptingBackend value that is not Mono, IL2CPP, or CoreCLR — e.g., a custom or experimental backend, or a corrupted PlayerSettings.scriptingBackend integer that maps to an invalid enum value.

Common situations: Editing ProjectSettings.asset manually and entering an invalid scriptingBackend integer, a Unity version introducing a new ScriptingBackend value not yet handled by this bindings file, or a platform-specific build pipeline setting an experimental backend.

Related errors

• ApiCompatibilityLevel.{0} is not supported!
• GetIl2CppBclDistributionDirectory is only supported for IL2C
• Scripting backend value {scriptingBackend} is not supported.
• Could not map typename 'GameManager' to type info (initializ
• Scene path "{0}" contains invalid directory separators.

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