Skip to main content
Version: Next

Common Errors

Currently submitted versions have all been tested and are basically unlikely to have compilation errors, crashes, or basic runtime errors. If you've checked the common errors but still can't resolve the issue, please update com.code-philosophy.hybridclr, hybridclr, and il2cpp_plus to the latest versions and try again. If the problem still persists, you can join the following groups:

  • Beginner Group 1: 428404198 (Full)
  • Beginner Group 2: **ThThe [BurstCompiler.StaticTypeReinit(type)] annotation on the assembly generated by dots has an error in the type name. For example: it generates this type name "GameLogic.TestSystem+GameLogic.codegenOnCreate_00000015$BurstDirectCall", but it should be "GameLogic.TestSystem+codegenOnCreate_00000015$BurstDirectCall", hybridclr encounters an error when reading this custom attribute and calling the il2cpp interface to parse the type.

There are several solutions:eLogic.TestSystem+GameLogic.codegenOnCreate_00000015$BurstDirectCall", but it should be "GameLogic.TestSystem+codegenOnCreate_00000015$BurstDirectCall",[BurstCompiler.StaticTypeReinit(type)] annotation on the assembly generated by dots has an error in the type name. For example: it generates this type name "GameLogic.TestSystem+GameLogic.codegenOnCreate_00000015$BurstDirectCall", but it should be "GameLogic.TestSystem+codegenOnCreate_00000015$BurstDirectCall", hybridclr encounters an error when reading this custom attribute and calling the il2cpp interface to parse the type.ameLogic.TestSystem+GameLogic.codegenOnCreate_00000015$BurstDirectCall", but it should be "GameLogic.TestSystem+codegenOnCreate_00000015$BurstDirectCall",GameLogic.TestSystem+GameLogic.codegenOnCreate_00000015$BurstDirectCall", correctly it should be "GameLogic.TestSystem+codegenOnCreate_00000015$BurstDirectCall",0274677 (Recommended)**

Unity Editor Errors​

Package name mismatch error with com.focus-creative-games.hybridclr_unity when installing com.code-philosophy.hybridclr in Package Manager​

Starting from version 3.0.0, com.focus-creative-games.hybridclr_unity was renamed to com.code-philosophy.hybridclr, so direct upgrade installation will cause this error.

Solution: First remove the old version of com.focus-creative-games.hybridclr_unity, then reinstall the latest version.

Cannot find HybridCLR settings interface when clicking HybridCLR/Setting​

Delete the ProjectSettings/HybridCLRSettings.asset file. If it still doesn't show, restart Unity Editor.

Win32Exception: ApplicationName='git', xxxx, Native error=The system cannot find the file specified. error during Installer installation​

This is because git is not installed (install GitForWindows on Windows. Install appropriately on other platforms), or Unity Editor and Unity Hub were not restarted after installing git. If you're sure git is installed and can run git in cmd, try restarting your computer.

Installer installation shows: git is not recognized as an internal or external command, or a runnable program​

Same as above.

DirectoryNotFoundException: Could not find a part of the path 'xxx' occurs during Installer installation​

Several possible reasons:

  • If the error directory doesn't exist, it's because git clone of hybridclr or il2cpp_plus repositories failed due to network or other issues. You can retry a few times.
  • If the error directory exists, it's because the path length exceeds 256 characters. Please avoid overly deep directories.

Installer installation prompts Mono.CompilerServices.SymbolWriter.dll path is too long. copy ignore!​

MonoBleedingEdge will be copied to HybridCLRData during installation, but the lib\mono directory within it is not actually used, so it has no impact.

Exception. region:UNITY_CONFIG start not find​

The hybridclr_unity version is too old. Please upgrade to the latest version.

Exception. region:PLACE_HOLDER start not find​

com.code-philosophy.hybridclr is a newer version, but the hybridclr code is too old.

Your hybridclr and il2cpp_plus must be on the main branch and updated to the latest version.

Exception. region:XXXXXX start not find​

Caused by version mismatch between com.code-philosophy.hybridclr and hybridclr/il2cpp_plus.

Requires the same version branch and both updated to the latest (or matching versions, but most people find it hard to know which versions match).

Exception: resolve assembly: yyyAssembly fail when running HybridCLR/generate/xxx​

If yyyAssembly is netstandard, it's because some assembly in the project references .net standard. There are several ways this error can occur:

Otherwise, it is because the dependent AOT or hot update DLLs were not found. There are several possible reasons for this:

NullReferenceException occurs when running HybridCLR/generate/xxx: HybridCLR.Editor.ABI.TypeCreatorBase.CreateTypeInfo ...​

If your com.code-philosophy.hybridclr package version is lower than 1.1.6, this is because your project contains conflicting DLLs with the same names as system DLLs, such as mscorlib.dll, System.Memory.dll, UnityEngine.dll, etc. This causes errors when parsing DLLs, as the wrong DLLs are read.

If the version is >= 1.1.6, generating bridge functions requires the trimmed AOT DLLs. If your AOT DLLs are outdated, types required by hot update code may be missing due to stripping. Therefore, you need to run generate/linkxml, then build or export the project to generate the trimmed AOT DLLs, and finally run your current generate/xxx command. Api Compatible Level is set to .net standard. Solution: Switch it to .Net 4.x or .Net Framework

AssembliesPostIl2CppStrip directory not generated when packaging iOS version​

Upgrade the com.code-philosophy.hybridclr package to v2.0.0 or above.

When running generate/all or generate/AOTDlls, the process tries to export the project to obtain trimmed AOT DLLs. If you previously disabled the Create Visual Studio Solution option during packaging, this error may occur due to Unity Editor's internal reasons.

The solution is to clear the il2cpp-related cache directories under Library and Temp, or simply delete these two directories.

If you still encounter this issue, you can manually build the project to generate the AOT DLLs, and then skip the generate/AOTDlls step.

Errors During Packaging​

Currently selected scripting backend (IL2CPP) is not installed​

Please install the il2cpp module in Unity Hub. Steps:

  • Switch to the Installers tab on the left side of Unity Hub
  • Right-click your current Unity version and select Add Modules, then choose the IL2CPP component for your platform (e.g., for Windows, select Windows Build Support (IL2CPP))
  • Install
  • Reopen Unity Editor

`Exception: C++ code bulider is unable to build C+ code. Inorder to build C++ code for Windows Destop, You must have one of these installed. xxxxx​

You haven't installed VS and Win 10 SDK. Please install VS, and install the Game development with C++ component in Visual Studio Installer. Choose the latest Win 10 SDK.

Encountered Undefined symbols for architecture arm64: "_objc_msgSend$initWithName:", referenced from: il2cpp::os::TimeZoneInfo::GetTimeZoneDataForID​

The Xcode version is too old. Update to a newer version.

Packaging errors with Undefined symbols: RuntimeApi_LoadMetadataForAOTAssembly or hybridclrApi_LoadMetadataForAOTAssembly​

The root cause is that you're using the original libil2cpp code. Several situations can lead to this result:

  • Scripting Backend incorrectly selected Mono
  • Enabled global installation option but didn't correctly replace libil2cpp in the Editor installation directory
  • com.code-philosophy.hybridclr version is lower than v3.1.0 and didn't replace the libil2cpp.a file in the Xcode project. Please compile the latest version according to the build iOS libil2cpp.a documentation. Then replace the libil2cpp.a file in the Xcode project

Building Library/Bee/artifacts/xxxx failed with output: Fatal error in Unity CIL Linker Mono.Cecil.AssemblyResolutionException: Failed to resolve assembly:'xxx'​

You mistakenly referenced the 'xxx' hot update dll in the main project. If you can't find where the reference is, try deleting the 'xxx' hot update module first and locate it based on compilation errors.

WebGL platform packaging encounters errors like undefine symbol: send file​

This error is unrelated to HybridCLR. This is because WebGL has restrictions on many functions. For example, the send file symbol missing is because IO-related functions cannot be called. When encountering problems, please remove those functions that WebGL platform doesn't support. Read Unity documentation for specifics.

Windows packaging encounters xxxx\\il2cpp\\libil2cpp\\utils\\Il2CppHashMap.h(71): error C2039: 'hash_compare': is not a member of 'stdext'​

This is caused by the latest VS version changes breaking some backward compatibility after .NET 7 release. com.code-philosophy.hybridclr v2.4.0 version has completely resolved this issue. You can upgrade to this version or revert to an older version of Visual Studio 2022 or use versions like 2019.

One solution that doesn't require reverting VS version is to modify HybridCLRData/LocalIl2CppData-{platform}/il2cpp/external/google/sparsehash/internal/sparseconfig.h, adding #define _SILENCE_STDEXT_HASH_DEPRECATION_WARNINGS. You can refer to the image below for modification.

stdext_error

For other solutions, see link

fatal error: 'icalls/mscorlib/System/MonoType.h' file not found #include "icalls/mscorlib/System/MonoType.h"​

You haven't generated the correct version macros. Please run HybridCLR/Generate/All before packaging.

Internal build system error. BuildProgram exited with code -2147024894.​

Internal build system error. BuildProgram exited with code -2147024894.
System.IO.FileNotFoundException: Could not load file or assembly 'Unity.IL2CPP.Bee.BuildLogic.WindowsDesktop, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null'. 
File name: 'Unity.IL2CPP.Bee.BuildLogic.WindowsDesktop, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null'

This is because you incorrectly set Scripting BackEngine to mono when the Installer was installed after switching Unity project versions, causing Build Tool mismatch. The solution is to reinstall once in HybridCLR/Installer....

DirectoryNotFoundException: xxxx\Library\Bee\artifacts\yyyy\ManagedStripted error during packaging​

You incorrectly set Scripting BackEngine to mono. Sometimes even though you previously switched to il2cpp, it may still be reset to mono by the Editor when switching platforms. The solution is to switch to il2cpp.

DirectoryNotFoundException: xxx\HybridCLRData\LocalIl2CppData-{yyy}\il2cpp\il2cpp-deps error when packaging WebGL platform​

WebGL must use global installation, i.e., useGlobal in HybridCLRSettings should be true. Remember that after each Generate/xxx, you must re-copy the {project}/HybridCLRData/LocalIl2CppData-{platform}/il2cpp/libil2cpp directory to the Editor installation directory before packaging. Otherwise, you may encounter errors like Scripting Missing or missing bridge functions.

Packaging encounters GC_set_mark_stck_empty function not found or signature mismatch error​

This is a problem caused by Unity modifying this function signature starting from Unity 2021.3.20. Update to com.code-philosophy.hybridclr 2.0.10+ version and reinstall to resolve.

Packaging WebGL platform shows build.js: undefined symbol: RuntimeApi_LoadMetadataForAOTAssembly (referenced by top-level compiled C/C++ code)​

WebGL uses global installation. You haven't replaced the original libil2cpp in the Editor installation directory with the local {project}/HybridCLRData/LocalIl2CppData-{platform}/il2cpp/libil2cpp, causing missing functions. The solution is:

  • Run HybridCLR/Generate/Il2cppDef to generate correct version macros
  • Copy {project}/HybridCLRData/LocalIl2CppData-{platform}/il2cpp/libil2cpp to replace the original libil2cpp in the Editor installation directory. Note that you must replace the directory, not merge directories, as this might cause extra files and compilation errors. You can also use symbolic links. For details, see the global installation documentation in Installing HybridCLR.

WebGL platform packaging errors when clicking Generate/All​

There are two reasons:

  • Haven't replaced the global installation libil2cpp or created its symbolic link
  • You're using com.code-philosophy.hybridclr 2.1.0 or higher, and didn't run HybridCLR/Generate/Il2cppDef once before replacing global libil2cpp, causing incorrect version macro generation and compilation errors.

Packaging shows #error: "not support unity version"​

There are several reasons:

  • You used a version lower than 2019 or higher than 2021, these versions are currently not supported
  • You didn't run HybridCLR/Generate/All or HybridCLR/Generate/Il2CppDef before packaging, causing Unity version macros not to be generated

Packaging shows 'could not find a part of path "xxxx/hybridclr/generated/UnityVersion.h"​

You didn't reinstall after updating the com.code-philosophy.hybridclr package, causing the local lil2cpp directory code to be too old.

Packaging finds "Undefined symbols for architecture arm64: "il2cpp::utils::Debugger::xxxxx"​

The reason is that the libil2cpp.a packaged by build_libil2cpp.sh is in release mode, which will cause compilation errors when compiled together with development mode projects.

The solution is to remove the development build option, or modify build_libil2cpp.sh yourself to package libil2cpp.a in debug mode.

Packaging shows error: undefined reference to 'SystemNative-ConvertErrorPalToPlatform'​

You're using a higher Unity version, and libil2cpp has added some new functions. The hybridclr version you're using is too old and doesn't include these high-version functions.

Solution: Upgrade hybridclr version and reinstall.

Packaging shows BuildFailedException: You must run HybridCLR/Installer after upgrading package​

Didn't execute Install after upgrading package. Install in HybridCLR/Installer.

Because starting from versions 2021.3.31 and 2022.3.11, this macro definition was modified, causing compilation errors on older hybridclr versions. The solution is to upgrade to the latest hybridclr version.

Shows error: no matching function for call to 'il2cpp_codegen_get_marshal_directive_exception'​

Because the hybridclr version you're using is too old and doesn't support your current Unity version. The solution is to upgrade to the latest hybridclr version.

General handling for compilation errors during packaging​

To a large extent, this is caused by mismatched versions between your package and hybridclr C++ code, or your Unity version is too new and not yet supported by hybridclr. You need to:

  • Update com.code-philosophy.hybridclr to the latest version
  • Install the latest version in HybridCLR/installer...
  • Run HybridCLR/generate/all to generate everything
  • Package

Packaging shows Building.BuilderFailedException: In file included from xxx\HybridCLRData\LocalIl2CppData-{platform}\il2cpp​

If your version is 2020.3.0-2020.3.25, after completing installation in the Installer, copy 2020.3.x/Editor/Data/il2cpp/external from any 2020.3.26+ version installation directory to replace {project}/HybridCLRData/LocalIl2CppData-{platform}/il2cpp/external

Packaging shows "HybridCLRDatal/Locall2CppData-WindowsEditor/il2cpp/llibil2cpp/hybridclr/generated/ReversePInvokeMethodStub.cpp: error: unknown type name'struct_xxx'"​

[MonoPInvokeCallback] functions in hot updates don't support structs as function parameters or return values. The solution is to delete these functions. If you must solve this problem, please contact paid technical support.

Packaging shows [CheckSettings] MethodBridge.cpp DEVELOPMENT flag:x is inconsistent with EditorUserBuildSettings.development:y. Please run 'HybridCLR/Generate/All' before building.​

The development option you used when generating bridge functions with Generate/All is inconsistent with packaging, which will cause bridge functions to have inconsistent object sizes with the actual AOT part, leading to serious errors. The solution is to run Generate/All again.

Building iOS, visionOS and other platform Xcode projects on Unity 6000 and 2023 versions shows Undefined symbols for architecture arm64: "CheckApplicationIntegrity(IntegrityCheckLevel)" linking error​

Principle:

When using certain functions in the UnityEngine.Debug class, since these functions are extern functions but not implemented in libIphone.a, this linking error occurs. Normally, since those functions are not used, packaging can proceed normally, but HybridCLR/Generate/LinkXml will preserve all for the UnityEngine.Debug class, triggering this error.

This problem is essentially caused by Unity's own bug. hybridclr 6.1.0 version temporarily works around this problem by ignoring the UnityEngine.Debug class in the generated link.xml file.

Solution:

Upgrade com.code-philosohpy.hybridclr to version 6.1.0+.

Building WeChat Mini Game platform on Tuanjie Engine shows "hybridclr doesn't support 'SLIM_GLOBAL_METADATA_FILE == 1' " error​

Tuanjie Engine 1.1.x's new metadata index slim optimization for WeChat Mini Game platform will cause hybridclr to not work properly on WeChat Mini Game platform. Starting from Tuanjie Engine 1.2.0, a Use Slim Format For global-metadata.dat option has been added to the WeixinMiniGame platform's Publishing Settings. Disabling this optimization allows normal use of hybridclr.

HybridCLR/Generate/All or building shows "PInvoke method {method.FullName} has unsupported parameter or return type. Please check the method signature."​

Extern functions defined in hot update code don't support parameters or return values like string or arrays. Please modify the corresponding parameters to IntPtr and manually marshal these parameters, or move the function to AOT for definition. For details, see PInvoke Support.

HybridCLR/Generate/All or building shows "MonoPInvokeCallback method {method.FullName} has unsupported parameter or return type. Please check the method signature."​

Functions with [MonoPInvokeCallback] attribute defined in hot update code don't support parameters or return values like string or arrays. Please modify the corresponding parameters to IntPtr and manually marshal these parameters, or move the function to AOT for definition. For details, see MonoPInvokCallback Support.

After upgrading to the latest version of Xcode, a compilation error occurs with the fopen function in the stdio.h header when publishing for the iOS platform After upgrading to Xcode 15.x​

an incompatibility issue with zlib arises. There are two solutions:

  • Roll back Xcode to version 13.x

  • Upgrade zlib to the latest version by replacing the code in the libil2cpp/external/zlib directory

Runtime Errors​

EntryPointNotFoundException. Unable to find entry point named 'RuntimeApi_LoadMetadataForAOTAssembly' in 'GameAssembly`​

There are several reasons:

  • Your current scripting backend is mono, please switch to il2cpp. Sometimes due to caching reasons, even after switching there may still be errors, please clear the Libraries directory and try again.
  • Global installation is enabled in HybridCLRSettings.

A scripted object (probably XXX?) has a different serialization layout when loading. Did you #ifdef UNITY_EDITOR a section of your serialized properties in any of your scripts?​

References to hot update scripts in AOT resources in the main project will cause this error. For example, resources under Resources referencing hot update scripts.

Scripts mounted on resources show Script Missing error​

There are several reasons:

  • Due to Unity's resource management implementation mechanism, resources must be packaged as AssetBundle to properly restore hot update scripts. Placing them under Resource doesn't work. For details, see MonoBehaviour Workflow.
  • The corresponding hot update assembly hasn't been loaded when loading resources
  • The assembly where the script is located hasn't been added to the hotUpdateDlls or preservedHotUpdateDlls list in HybridCLR Settings
  • After modifying the hotUpdateDlls or preservedHotUpdateDlls list in HybridCLR Settings, didn't Generate/All and rebuild the main package

Encountering "This icall is not supported by il2cpp at System.AppDomain.Load"​

There are two reasons:

  1. If iOS platform, because iOS platform doesn't compile libil2cpp from source code but uses pre-compiled libil2cpp.a, you need to replace libil2cpp.a in the xcode project with HybridCLR's compiled version. For compilation method, see build libil2cpp.a for iOS
  2. If WebGL platform, it's because after using global installation, you didn't replace the libil2cpp in the installation directory or didn't create a symbolic link from the installation directory libil2cpp to the project's local libil2cpp. For details, see Publishing WebGL Platform
  3. If other platforms, it's because HybridCLR is not installed. Please follow the Installing HybridCLR documentation.

Physics collision Collision not working in hot updates​

This is generally caused by the Collision script and related functions being stripped. Please ensure that related scripts and dlls are not stripped.

unsupported internal call for il2cpp. xxxx​

Called a function that exists in Mono but is not implemented in il2cpp. Please modify the code to not use these classes and functions.

async code (system built-in or UniTask, etc.) throws NullReferenceException or crashes at runtime after packaging​

There are several reasons:

  • Exceptions are thrown in asynchronous code (such as bridge function exceptions or AOT generic instantiation exceptions), causing asynchronous code to fail to execute correctly. The solution is to catch exceptions in async code, locate the specific cause, and then solve it
  • Supplemental metadata and bridge functions don't match the final release package. This problem occurs when the development option is enabled: Generate/All or Generate/AOTDlls generates aot dll in non-development mode, which doesn't match the development aot dll generated during packaging, further causing both supplemental metadata and generated bridge functions to be incorrect, thus serious errors or crashes occur at runtime. The solution is not to turn off the development option when packaging, or modify the Generate/AOTDlls code to add the Development flag in BuildOptions.

Encountering Unity: TypeLoadException: Could not load type 'XxxType' from assembly 'yyyAssembly'​

There are several situations:

Situation 1: yyyAssembly is netstandard​

This is because you set api compatible level to .net standard in Player Settings.

Currently supports .net standard 2.0 and .net 4.x, but even if the main project is packaged with .net standard, hot update dll packaging must use .net 4.x. The reason is that when unity packages with .net standard, it automatically strips .net standard dependencies and directly depends on the final dll, causing the main project's dll list to actually not contain the net standard dll, which in turn causes the hot update dll to fail to find objects from netstandard when loading.

The solution is to use .net 4.x for both packaging and compiling hot updates, or use .net standard 2.0 for packaging but switch api compatible level to .net 4.x (renamed to .net framework starting from 2021) when compiling hot update parts.

Situation 2: yyyAssembly is other AOT assembly​

This is function loss caused by unity code stripping, you can handle it using conventional ways to avoid unity code stripping.

According to Unity anti-stripping principles, you can add references to missing code classes in link.xml, but this is time-consuming and laborious.

HybridCLR provides a convenient automatic generation tool. Run the menu command HybridCLR/Generate/LinkXml to generate link.xml based on hot update dlls.

caution

If you find that this class is indeed preserved in link.xml, but this type missing error still occurs, this is caused by Unity itself. Unity requires that any class in the dll must be referenced in the code to retain this dll, and those configurations in link will take effect. Therefore, you need to manually reference any class in the dll where the missing class is located in your code.

Situation 3: yyyAssembly is hot update assembly​

This is because you did not load hot update dlls in dependency order. For example, if A depends on B, then you should load B first, then load A.

MissingMethodException: HybridCLR.RuntimeApi::LoadMetadataForAOTAssembly(System.Byte[],HybridCLR.HomologousImageMode) error​

Failed to reinstall after upgrading hybridclr. Starting from v4.0.8, extern functions defined in RuntimeApi were changed from PInvoke to InternalCall. If you don't reinstall after upgrading the hybridclr package, this error will occur.

MissingMethodException: MethodNotFind xxClass::yyyMethod error​

This is function loss caused by unity code stripping. Run the menu command HybridCLR/Generate/LinkXml to generate link.xml based on hot update dlls. Also ensure that referenced AOT assemblies are referenced in the main project code, otherwise linkxml will not take effect.

MissingMethodException: AOT generic method isn't instantiated in aot module xxx​

There are several reasons:

  1. This is caused by missing AOT generic function instantiation
  2. Using Unity 2021 and the Il2Cpp Code Generation option is faster (smaller) build, causing the generated code to be in full generic mode, and all generic function signatures are changed. If supplemental metadata is not provided, calling generic functions that are already instantiated in AOT will still cause this error.
  3. WeChat Mini Game conversion tool defaults to setting IL2CPP Code Generation to Faster(Smaller) builds mode. If supplemental metadata is not provided, it will cause inability to access AOT generic functions.

Solution for reason 1:

  • The error log tells you which AOT function instantiation is missing. You add a call to this function in the main project, so that il2cpp can generate code for this generic function when packaging. You can add this generic AOT function call anywhere in the main project. Currently, it's generally concentrated in the RefTypes.cs file.
  • Use supplemental metadata technology

Solution for reason 2:

  • Set IL2CPP Code Generation in BuildSettings to Faster runtime while using supplemental metadata

Solution for reason 3:

  • Use supplemental metadata technology
  • Modify the WeChat tool source code yourself and set IL2CPP Code Generation in BuildSettings to Faster.

For specific operations, please see the AOT Generic Principle Introduction document.

Encountering ExecutionEngineException: metadata type not match​

Supplemental metadata used a mismatched stripped AOT version. Should use the version generated by this packaging, or use HomologousImageMode::SuperSet mode to load.

Encountering ExecutionEngineException: not support extern method: xxxx​

There are two reasons:

  • Defined extern functions in hot updates, which is temporarily not supported. The solution is to move extern functions to the AOT part.
  • Used SuperSet metadata format, but the supplemental metadata aot dll is too old, causing generics in AOT to not be found in the supplemental metadata dll. The solution is to update the latest AOT dll.

Encountering ExecutionEngineException:method body is null. xxx::yyyy​

Same reason as above.

Encountering ExecutionEngineException: GetManaged2NativeMethodPointer not support. xxxx function name​

Missing interpreter -> aot direction bridge functions. Please first confirm that your hybridclr is the latest code, com.code-philosophy.hybridclr package is also the latest version, and you have generated the latest bridge functions. For the principle, please refer to Bridge Functions.

If it works normally on Android but has problems on iOS, it's because you didn't recompile libil2cpp.a.

If there are still problems, please report to the administrator for technical support in the group.

Encountering 'ExecutionEngineException: NotSupportNative2Managed'​

Missing aot -> interpreter direction bridge functions. Please first confirm that you have generated the latest bridge functions. For the principle, please refer to Bridge Functions. If it works normally on Android but has problems on iOS, it's because you didn't recompile libil2cpp.a.

If there are still problems, please report to the administrator for technical support in the group.

Encountering ExecutionEngineException: NotSupportManaged2NativeFunctionMethod​

This is caused by missing bridge functions for extern functions defined in hot update code. Please reserve bridge functions related to extern functions in advance when building the main package. For details, see the document PInvoke Support.

ExecutionEngineException: Attempting to call method 'xxxx' for which no ahead of time (AOT) code was generated​

Just supplement metadata for the dll where the error function is located.

GetReversePInvokeWrapper fail. exceed max wrapper num of method​

Insufficient Wrapper functions. You need to reserve Wrapper functions for functions in hot updates that have the MonoPInvokeCallback attribute added. For details, see MonoPInvokeCallback Support

NotSupportedException: To marshal a managed method, please add an attribute named 'MonoPInvokeCallback' to the method definition. The method we're attempting to marshal is:xxxx​

Same principle as above

When using addressable for hot updates, loading resources shows UnityEngine.AddressableAssets.InvalidKeyException: Exception of type 'UnityEngine.AddressableAssets.InvalidKeyException' was thrown. No Asset found with for key 'xxxx' exception​

The solution comes from Resource loading error caused by combining addressables and HybridCLR. You can also refer to the video Practical Pitfalls: Importing HybridCLR into your own project and implementing hot updates starting from 1:02:30.

When using addressables to update hot update dlls. Since the Addressables LoadAssetAsync function is used first, Addressables needs to be initialized first. If the resource type in this initialization is a hot update type, Addressables will consider the resource type as System.Object. So you need to load the dll first before you can use Addressables to load resources, otherwise it will report UnityEngine.AddressableAssets.InvalidKeyException: Exception of type 'UnityEngine.AddressableAssets.InvalidKeyException' was thrown. No Asset found with for Key=xxx. Key exists as Type=System.Object, which is not assignable from the requested Type=YourHotUpdateAssetType.

The solutions are as follows:

  • Use the LoadAsset<System.Object> interface to load and then cast
  • Reload the catalog after loaddll ends Addressables.LoadContentCatalogAsync($"{Addressables.RuntimePath}/catalog.json");

GameObject.GetComponent(string name) interface cannot get components​

This is a known bug, related to unity's code implementation. Only hot update scripts mounted on hot update resources will have this problem. Hot update scripts added through AddComponent in code can be found using this method. Please use GameObject.GetComponent<T>() or GameObject.GetComponent(typeof(T)) instead

GameObject.GetComponent<T>() or GameObject.GetComponent(Type type) returns null​

This is because you loaded an assembly twice. The T or Type you passed in is only the same name as the script mounted on GameObject, but belongs to different assembly instances, causing it to become null after casting when returning. Generally, the following situations cause this:

  • Using Assembly.Load to load hot update assemblies in Editor. Since all assemblies are already loaded by default in Editor, loading again will cause duplicate loading. The solution is to comment out the loading code using #if !UNITY_EDITOR macro
  • Assembly not added to hotUpdateAssemblies list, causing hot update assembly to be packaged into AOT. Loading again in hot update will cause duplicate loading. The solution is to add the hot update assembly to the hotUpdateAssemblies list and repackage

Using MemoryProfile to capture memory snapshots crashes​

If you're using Unity 2021 or higher, upgrade hybridclr package to v3.0.2 or higher. If using Unity 2019 or 2020, merge the changes from commit record Fix crash bug when using Memory Profiler to create snapshots to your current version.

profiler's BeginSample and EndSample cannot take effect​

Because functions like BeginSample have [Condition] compilation annotations, when compiling dll in Release mode, these codes will be automatically removed, causing Profile to become ineffective. The solution is to compile hot update dll in Development mode, code as follows. If you use v3.0.2 and higher versions, the HybridCLR/CompileDll/ActivedBuildTarget_Development menu command is already included.

    var group = BuildPipeline.GetBuildTargetGroup(target);

    ScriptCompilationSettings scriptCompilationSettings = new ScriptCompilationSettings();
    scriptCompilationSettings.group = group;
    scriptCompilationSettings.target = target;
    if (developmentBuild)
    {
        // The core is this line, which compiles dll in Debug mode, preserving function calls like Profiler.BeginSample.
        scriptCompilationSettings.options |= ScriptCompilationOptions.DevelopmentBuild;
    }
    Directory.CreateDirectory(buildDir);
    ScriptCompilationResult scriptCompilationResult = PlayerBuildInterface.CompilePlayerScripts(scriptCompilationSettings, buildDir);

iOS camera has no response but doesn't report errors​

This is caused by WebCamTexture.devices not being preserved in AOT. You need to manually reference WebCamTexture.devices in AOT.

AVProMovieCapture plugin not working properly​

Due to AVProMovieCapture's own implementation, you need to initialize the plugin first before performing HybridCLR loading and other operations.

EncodeImageAndMetadataIndex function encountering IL2CPP_ASSERT assertion failure error​

This is caused by your project's hot update dll being too large. Solution:

  • Upgrade to v5.2.0+ version, which supports dlls up to 64M
  • Split the hot update dll into multiple smaller dlls

Crash when calling ResourceCatalogData::GetGUIDFromPath during AutomaticWorldBootstrap::Initialize at startup​

The entities version you are currently using cannot be directly used for Player Building packaging. You must install com.unity.platforms and use its separate packaging method. Detailed documentation.

Hot update assembly references Unity.Entities, runtime throws exception DllNotFoundException: netstandard​

Under normal circumstances, netstandard assemblies will be pruned during the build process. This can be resolved by preserving netstandard in link.xml.

Encountering Invalid type name exception when running DOTS​

The [BurstCompiler.StaticTypeReinit(type)] annotation on the assembly generated by dots has an error in the type name. For example: it generates this type name "GameLogic.TestSystem+GameLogic.codegenOnCreate_00000015$BurstDirectCall", but it should be "GameLogic.TestSystem+codegenOnCreate_00000015$BurstDirectCall", hybridclr encounters an error when reading this custom attribute and calling the il2cpp interface to parse the type.

There are several solutions:

  • Modify the implementation of il2cpp::vm::Type::TypeNameParser::ParseTypeName to enable it to read the malformed names generated by dots
  • Remove the namespace of System, ComponentData and other types, so that the nested subtypes will not incorrectly include the namespace, and in this case the name can be parsed correctly
  • Report to Unity to have them fix this bug

For similar issues, refer to issue#164.

Job.ScheduleBatch crashes​

This is caused by hybridclr being incompatible with dots. The commercial version can solve this problem.

Unable to load il2cpp error occurs when the game starts​

This is because the hybridclr you are currently using is not compatible with your Unity version. Generally, this is because your version is too new, and your current hybridclr has not timely merged the code changes of the il2cpp of your current version.

Please upgrade hybridclr to the latest version and repackage. If there are still problems, please report to us, and we will release a new version within a week to solve this compatibility issue.

WebGL runtime shows function signature mismatch error​

WebGL platform packaging uses the faster (smaller) build option by default, which enables full generic sharing. The community version must supplement metadata to work with the full generic sharing mechanism. Please try the following solutions in order:

  1. Ensure hybridclr is v4.0.0+ version. If below this version, please upgrade
  2. If there are still problems, it may be caused by bridge functions not matching the final built package, such as enabling 'development' during 'Generate/all' but not enabling 'development' during building. The solution is to use build-time parameters, run generate/all, clear build cache and rebuild
  3. If there are still problems, switch IL2CPP Code Generation in Player Settings to Faster Runtime
  4. If there are still problems, upgrade to the latest hybridclr version
  5. If there are still problems, please contact our technical support

webgl (or WeChat Mini Game, etc.) on iOS 15.4 system shows "Not implemented", "Class::FromIl2CppType" error logs, stuck on startup screen unable to start​

This is a Unity & iOS 15.4 BUG. There are two solutions:

  1. WeChat's provided wasm code subpackaging (recommended)
  2. Unity WebGL official forum's temporary fix. Specifically, open the HybridCLRData/LocalIl2CppData-xxx/il2cpp/libil2cpp/metadata/GenericMetadata.cpp file, add a line #pragma clang optimize off before the code line const Il2CppType* GenericMetadata::InflateIfNeeded function, and add #pragma clang optimize on after the function. The final code looks like this:
#pragma clang optimize off
    const Il2CppType* GenericMetadata::InflateIfNeeded(const Il2CppType* type, const Il2CppGenericContext* context, bool inflateMethodVars)
    {
        // ...
    }
#pragma clang optimize on

NotSupportNative2Managed bridge function missing exception after using Unity.netcode.runtime​

The reason is that NetworkManager.RpcReceiveHandler in Unity.netcode.runtime.dll is internal, defined as follows:

internal delegate void RpcReceiveHandler(NetworkBehaviour behaviour, FastBufferReader reader, __RpcParams parameters);

This causes the generation tool to not generate bridge functions for it. But Unity very trickily generates RpcReceiveHandler handling functions for functions marked with [ClientRpc] and [ServerRpc] during packaging, and references the internal RpcReceiveHandler class! It doesn't even report an error. This causes the missing bridge function problem.

The solution is to also define a delegate with the same signature in your AOT project.

    // Since __RpcParams is also internal, we redefine the same type here
    public struct __RpcParams
#pragma warning restore IDE1006 // restore naming rule violation check
    {
        public ServerRpcParams Server;
        public ClientRpcParams Client;
    }

    public delegate void MyRpcReceiveHandler(NetworkBehaviour behaviour, FastBufferReader reader, __RpcParams parameters);