egametang/ET · critical · BuildFailedException

You must run `HybridCLR/Installer` after upgrading package

Error message

You must run `HybridCLR/Installer` after upgrading package

What it means

Thrown by CheckSettings.OnPreprocessBuild when the HybridCLR package version does not match the version of libil2cpp that was patched during installation. After upgrading the HybridCLR package, the installer must be re-run to apply new patches to libil2cpp. If the versions diverge, the build is aborted because the stale patches would produce incorrect or broken hot-update code.

Source

Thrown at Packages/cn.etetet.hybridclr/Scripts/Editor/Share/BuildProcessors/CheckSettings.cs:65

            }
            BuildTargetGroup buildTargetGroup = BuildPipeline.GetBuildTargetGroup(EditorUserBuildSettings.activeBuildTarget);
            ScriptingImplementation curScriptingImplementation = PlayerSettings.GetScriptingBackend(NamedBuildTarget.FromBuildTargetGroup(buildTargetGroup));
            ScriptingImplementation targetScriptingImplementation = ScriptingImplementation.IL2CPP;
            if (curScriptingImplementation != targetScriptingImplementation)
            {
                Debug.LogError($"[CheckSettings] current ScriptingBackend:{curScriptingImplementation}，have been switched to:{targetScriptingImplementation} automatically");
                PlayerSettings.SetScriptingBackend(NamedBuildTarget.FromBuildTargetGroup(buildTargetGroup), targetScriptingImplementation);
            }

            var installer = new Installer.InstallerController();
            if (!installer.HasInstalledHybridCLR())
            {
                throw new BuildFailedException($"You have not initialized HybridCLR, please install it via menu 'HybridCLR/Installer'");
            }

            if (installer.PackageVersion != installer.InstalledLibil2cppVersion)
            {
                throw new BuildFailedException($"You must run `HybridCLR/Installer` after upgrading package");
            }

            HybridCLRSettings gs = SettingsUtil.HybridCLRSettings;
            if (((gs.hotUpdateAssemblies?.Length + gs.hotUpdateAssemblyDefinitions?.Length) ?? 0) == 0)
            {
                Debug.LogWarning("[CheckSettings] No hot update modules configured in HybridCLRSettings");
            }

            if (!DisableMethodBridgeDevelopmentFlagChecking)
            {
                string methodBridgeFile = $"{SettingsUtil.GeneratedCppDir}/MethodBridge.cpp";
                var match = Regex.Match(File.ReadAllText(methodBridgeFile), @"// DEVELOPMENT=(\d)");
                if (match.Success)
                {
                    int developmentFlagInMethodBridge = int.Parse(match.Groups[1].Value);
                    int developmentFlagInEditorSettings = EditorUserBuildSettings.development ? 1 : 0;
                    if (developmentFlagInMethodBridge != developmentFlagInEditorSettings)
                    {

View on GitHub (pinned to 5cab01f7a8)

Solutions

Run HybridCLR > Installer > Install again to patch libil2cpp with the current package version, then rebuild.
Verify the package version in Packages/manifest.json matches what you expect after upgrade.
For CI/CD, always run the installer step after pulling dependency updates.
If the installer itself fails, check the console for the specific error and resolve it before retrying.

Example fix

// workflow fix — no code change:
// 1. Upgrade HybridCLR package via Package Manager
// 2. Unity menu > HybridCLR > Installer > Install
// 3. Rebuild

// for automation:
// -executeMethod HybridCLR.Editor.Installer.InstallController.Install
// then build

// before
if (installer.PackageVersion != installer.InstalledLibil2cppVersion)
    throw new BuildFailedException(...);

// after — informative guidance
if (installer.PackageVersion != installer.InstalledLibil2cppVersion)
{
    Debug.LogError($"Version mismatch: package={installer.PackageVersion}, installed={installer.InstalledLibil2cppVersion}. Run HybridCLR > Installer.");
    return;
}

Defensive patterns

Strategy: validation

Validate before calling

var installer = new Installer.InstallerController();
if (installer.PackageVersion != installer.InstalledLibil2cppVersion)
{
    Debug.LogError($"HybridCLR version mismatch: package={installer.PackageVersion}, " +
        $"installed={installer.InstalledLibil2cppVersion}. Run HybridCLR > Installer to update.");
    return;
}

Try / catch

try
{
    BuildPipeline.BuildPlayer(scenes, outputPath, buildTarget, buildOptions);
}
catch (BuildFailedException ex) when (ex.Message.Contains("after upgrading package"))
{
    Debug.LogError("HybridCLR package version changed. Run HybridCLR > Installer > Install, then rebuild.");
}

Prevention

After upgrading the HybridCLR package via Package Manager, always re-run the installer.
For CI/CD, run the installer step every time dependencies are updated.
Communicate package upgrades to all team members so they re-run the installer locally.
Check installer.PackageVersion vs InstalledLibil2cppVersion before building to catch mismatches early.

When it happens

Trigger: Building with HybridCLR enabled after the package was upgraded (e.g. via UPM/registry) but the installer was not re-run. PackageVersion reflects the current package, InstalledLibil2cppVersion reflects what the installer last wrote; a mismatch means the local libil2cpp is stale.

Common situations: Upgrading the HybridCLR Unity package via Package Manager without re-running the installer; a teammate pulls new code with a newer package version but didn't run the installer; the Library folder was partially cleared, resetting one version but not the other.

Related errors

AI-assisted analysis of egametang/ET@5cab01f7a8 (2026-08-13). Data as JSON: /api/errors/1eeb73b349ea7e43. Report an issue: GitHub.