egametang/ET · error · BuildFailedException

hot update assembly:{hotUpdateDllName} doesn't exist

Error message

hot update assembly:{hotUpdateDllName} doesn't exist

What it means

Thrown during the Unity build pipeline by FilterHotFixAssemblies when a hot update assembly name configured in HybridCLRSettings does not correspond to any assembly in the build list and cannot be resolved by the hot update assembly resolver. HybridCLR needs every declared hot update DLL to be a real, compiled assembly so it can strip it from the AOT build and load it at runtime instead.

Source

Thrown at Packages/cn.etetet.hybridclr/Scripts/Editor/Share/BuildProcessors/FilterHotFixAssemblies.cs:51

            {
                if (string.IsNullOrWhiteSpace(hotUpdateDll))
                {
                    throw new BuildFailedException($"hot update assembly name cann't be empty");
                }
                if (!hotUpdateDllSet.Add(hotUpdateDll))
                {
                    throw new BuildFailedException($"hot update assembly:{hotUpdateDll} is duplicated");
                }
            }

            var assResolver = MetaUtil.CreateHotUpdateAssemblyResolver(EditorUserBuildSettings.activeBuildTarget, allHotUpdateDllNames);
            // 检查是否填写了正确的dll名称
            foreach (var hotUpdateDllName in allHotUpdateDllNames)
            {
                if (assemblies.Select(Path.GetFileNameWithoutExtension).All(ass => ass != hotUpdateDllName) 
                    && string.IsNullOrEmpty(assResolver.ResolveAssembly(hotUpdateDllName, false)))
                {
                    throw new BuildFailedException($"hot update assembly:{hotUpdateDllName} doesn't exist");
                }
            }

            // 将热更dll从打包列表中移除
            return assemblies.Where(ass =>
            {
                string assName = Path.GetFileNameWithoutExtension(ass);
                bool reserved = allHotUpdateDllNames.All(dll => !assName.Equals(dll, StringComparison.Ordinal));
                if (!reserved)
                {
                    Debug.Log($"[FilterHotFixAssemblies] filter assembly:{assName}");
                }
                return reserved;
            }).ToArray();
        }
    }
}

View on GitHub (pinned to 5cab01f7a8)

Solutions

1. Open HybridCLR Settings (Edit > Project Settings > HybridCLR) and verify every entry in Hot Update Assemblies is the bare assembly name (no path, no .dll) of an assembly that actually compiles in the project.
2. If the hot update DLL is produced outside the main Unity project, add its output directory to the External Hot Update Path setting so the resolver can find it.
3. Remove any stale or renamed entries from the list and re-run the build.
4. Check the Editor log for the exact DLL name printed in the exception and grep the project for that name to confirm whether the assembly still exists.

Example fix

// before (settings contain a typo or stale name)
HotUpdateAssemblies = [ "MyGame.Hotfix", "MyGame.Hottfix" ]
// after
HotUpdateAssemblies = [ "MyGame.Hotfix" ]

// Before building, verify every configured hot update assembly name resolves
var resolver = MetaUtil.CreateHotUpdateAssemblyResolver(EditorUserBuildSettings.activeBuildTarget, SettingsUtil.HotUpdateAssemblyNames);
foreach (var name in SettingsUtil.HotUpdateAssemblyNames)
{
    if (string.IsNullOrEmpty(resolver.ResolveAssembly(name, false)))
        Debug.LogError("Hot update assembly " + name + " will fail the build: not found.");
}

When it happens

Trigger: Build processing iterates allHotUpdateDllNames (from HybridCLRSettings.HotUpdateAssemblies). For each name it checks whether any file in the build's assembly list matches (via Path.GetFileNameWithoutExtension) and falls back to assResolver.ResolveAssembly(name, false). If both fail, this exception aborts the build.

Common situations: A typo in the Hot Update Assemblies list in the HybridCLR settings inspector; an assembly that was renamed or deleted from the project; a hot update DLL that lives in a separate solution/scope not visible to the resolver; an assembly defined with .dll extension in the settings instead of the bare name.

Related errors

• resolve Hot update dll:{assemblyName} failed! Please make su
• hot update assembly name cann't be empty
• hot update assembly:{hotUpdateDll} is duplicated
• GenerateStripedAOTDlls failed
• resolve AOT dll:{assemblyName} failed! Please make sure that

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