Unity-Technologies/UnityCsReference · error · ArgumentException

Unhandled scripting backend

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.

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.
• GetIl2CppBclDistributionDirectory is only supported for…
• Scripting backend value
• AssetBundleBuild cannot be null.
• Attempting to set an incorrect number of icons for

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

Appendix: 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)