egametang/ET · critical · BuildFailedException

You have not initialized HybridCLR, please install it via me

Error message

You have not initialized HybridCLR, please install it via menu 'HybridCLR/Installer'

What it means

Thrown by CheckSettings.OnPreprocessBuild (IPreprocessBuildWithReport callback) when InstallerController.HasInstalledHybridCLR() returns false. This runs at the start of every build when HybridCLR is enabled. HasInstalledHybridCLR checks whether the local libil2cpp has been patched with HybridCLR's modifications; if not, the build would fail or produce non-functional hot-update support, so it aborts early with BuildFailedException.

Source

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

                }
            }
            if (!globalSettings.enable)
            {
                return;
            }
            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)

View on GitHub (pinned to 5cab01f7a8)

Solutions

In the Unity editor menu, go to HybridCLR > Installer and click Install, then retry the build.
If the installer reports errors, check the console for the specific failure (network, permissions, git) and resolve it.
After upgrading Unity, always re-run the installer since the libil2cpp source is replaced.
For CI/CD, add a step that runs the installer via the editor API before building.

Example fix

// workflow fix — no code change needed:
// Unity menu > HybridCLR > Installer > Install
// then rebuild.

// for CI/CD automation, run this in batchmode before building:
// -executeMethod HybridCLR.Editor.Installer.InstallController.Install

// before — build fails
// throw new BuildFailedException("You have not initialized HybridCLR...");

// after — check and guide the user
if (!installer.HasInstalledHybridCLR())
{
    Debug.LogError("HybridCLR not installed. Run menu: HybridCLR > Installer > Install, then rebuild.");
    return; // skip build or prompt
}

Defensive patterns

Strategy: validation

Validate before calling

var installer = new Installer.InstallerController();
if (!installer.HasInstalledHybridCLR())
{
    Debug.LogError("HybridCLR is not installed. Run Unity menu: HybridCLR > Installer > Install, then rebuild.");
    return; // do not proceed with the build
}

Try / catch

try
{
    // Build triggers CheckSettings.OnPreprocessBuild internally
    BuildPipeline.BuildPlayer(scenes, outputPath, buildTarget, buildOptions);
}
catch (BuildFailedException ex) when (ex.Message.Contains("not initialized HybridCLR"))
{
    Debug.LogError("HybridCLR not installed. Open HybridCLR > Installer and click Install, then rebuild.");
}

Prevention

After cloning a HybridCLR project, always run HybridCLR > Installer before building.
After deleting the Library folder or reinstalling Unity, re-run the installer.
For CI/CD pipelines, add an installer step via -executeMethod before the build command.
Document the installer step in project onboarding instructions.

When it happens

Trigger: Building the project (any platform) with HybridCLR enabled in HybridCLRSettings, but the HybridCLR installer has never been run or its modifications were removed (e.g. Unity reinstalled, library folder cleared, il2cpp re-cached). The check fires during the build preprocessing phase.

Common situations: Fresh clone of a project using HybridCLR without running the installer; deleting the Library folder which clears the installed state; upgrading Unity which replaces the bundled libil2cpp and wipes HybridCLR patches; switching to a new machine without running the installer.

Related errors

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