{"record":{"id":"23841b87972a6e2a","repo":"stride3d/stride","slug":"failed-to-initialize-msdfgen-context","errorCode":null,"errorMessage":"Failed to initialize msdfgen context","messagePattern":"Failed to initialize msdfgen context","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"sources/engine/Stride.Assets/SpriteFont/Compiler/SignedDistanceFieldFontImporter.cs","lineNumber":55,"sourceCode":"        /// <inheritdoc/>\n        public void Import(SpriteFontAsset options, List<char> characters)\n        {\n            fontSource = options.FontSource.GetFontPath();\n            if (string.IsNullOrEmpty(fontSource))\n                return;\n\n            NativeLibraryHelper.PreloadLibrary(\"freetype\", typeof(SignedDistanceFieldFontImporter));\n            NativeLibraryHelper.PreloadLibrary(\"stride_msdfgen\", typeof(SignedDistanceFieldFontImporter));\n\n            int err = FreeTypeNative.FT_Init_FreeType(out var library);\n            if (err != 0)\n                throw new InvalidOperationException($\"Failed to initialize FreeType library (error {err})\");\n\n            msdfgenContext = MsdfgenNative.msdfgenContextCreate();\n            if (msdfgenContext == IntPtr.Zero)\n            {\n                FreeTypeNative.FT_Done_FreeType(library);\n                throw new InvalidOperationException(\"Failed to initialize msdfgen context\");\n            }\n\n            msdfgenFont = MsdfgenNative.msdfgenLoadFont(msdfgenContext, fontSource);\n            if (msdfgenFont == IntPtr.Zero)\n            {\n                MsdfgenNative.msdfgenContextDestroy(msdfgenContext);\n                msdfgenContext = IntPtr.Zero;\n                FreeTypeNative.FT_Done_FreeType(library);\n                throw new AssetException($\"Failed to load font '{fontSource}' into msdfgen.\");\n            }\n\n            try\n            {\n                var fontData = File.ReadAllBytes(fontSource);\n                var handle = GCHandle.Alloc(fontData, GCHandleType.Pinned);\n\n                try\n                {","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/engine/Stride.Assets/SpriteFont/Compiler/SignedDistanceFieldFontImporter.cs#L37-L73","documentation":"After FreeType initializes, Import creates the msdfgen processing context with msdfgenContextCreate. If it returns IntPtr.Zero the native msdfgen library failed to create its context; the importer frees the FreeType library and throws this InvalidOperationException. Without this context no multi-channel signed distance fields can be generated.","triggerScenarios":"Calling SignedDistanceFieldFontImporter.Import when the native msdfgen context creation returns a null pointer — e.g. stride_msdfgen failed to preload correctly, native memory allocation failure, or a broken/mismatched msdfgen binary.","commonSituations":"Missing stride_msdfgen native dependency in the output folder; an msdfgen build incompatible with the target platform; out-of-memory on constrained build agents; mixing Stride versions where native libs and managed assemblies disagree.","solutions":["Ensure the stride_msdfgen native library for the target platform is present and loadable (check loader errors around the NativeLibraryHelper preload).","Reinstall or rebuild Stride's native dependencies so managed and native versions match.","Check available memory on the build machine; context creation can fail on allocation failure.","Upgrade to a Stride version where the msdfgen platform issue is fixed if you are on an affected platform."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// ensure the native msdfgen dependency is present before import\nNativeLibraryHelper.PreloadLibrary(\"stride_msdfgen\", typeof(SignedDistanceFieldFontImporter));\n// optionally probe free memory; context creation can fail on allocation failure\nif (GC.GetTotalMemory(forceFullCollection: false) > threshold) GC.Collect();","typeGuard":"bool MsdfgenAvailable() => NativeLibrary.TryLoad(\"stride_msdfgen\", out _);","tryCatchPattern":"try\n{\n    importer.Import(fontSource, characters, options);\n}\ncatch (InvalidOperationException ex) when (ex.Message == \"Failed to initialize msdfgen context\")\n{\n    logger.LogError(ex, \"msdfgen context creation failed. Verify stride_msdfgen native library presence/version and available memory.\");\n    throw; // environmental failure — fix native deps or memory, then rerun\n}","preventionTips":["Ship the stride_msdfgen native library for every platform you build fonts on.","Keep Stride managed and native components on the same version to avoid ABI mismatches.","Ensure build agents have sufficient free memory for native allocation.","Run a minimal SDF font compile as a CI canary to catch native init regressions early."],"tags":["native","msdfgen","fonts","initialization"],"backgroundTag":"module-init-failed","analyzedSha":"96fad776d210c221682aac1ccdf4c79dc046fc38","analyzedAt":"2026-09-14T02:59:31.279Z","contentChangedAt":"2026-09-14T02:59:31.279Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}