{"record":{"id":"c12c757095a09bd5","repo":"stride3d/stride","slug":"failed-to-initialize-freetype-library-error-err-c12c75","errorCode":null,"errorMessage":"Failed to initialize FreeType library (error {err})","messagePattern":"Failed to initialize FreeType library \\(error (.+?)\\)","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"sources/engine/Stride.Assets/SpriteFont/Compiler/SignedDistanceFieldFontImporter.cs","lineNumber":49,"sourceCode":"        public float BaseLine { get; private set; }\n\n        private string fontSource;\n        private IntPtr msdfgenContext;\n        private IntPtr msdfgenFont;\n\n        /// <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","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/engine/Stride.Assets/SpriteFont/Compiler/SignedDistanceFieldFontImporter.cs#L31-L67","documentation":"SignedDistanceFieldFontImporter.Import initializes the native FreeType library via FT_Init_FreeType before any SDF generation. A non-zero return code means the native freetype library could not initialize; the importer throws this InvalidOperationException including the FreeType error code. This typically indicates the native freetype binary could not be loaded or its runtime state is broken on the target machine.","triggerScenarios":"First call to SignedDistanceFieldFontImporter.Import for an SDF font when FT_Init_FreeType returns an error — usually right after NativeLibraryHelper.PreloadLibrary(\"freetype\", ...) loaded a missing or incompatible native binary.","commonSituations":"Missing or mismatched native freetype/stride_msdfgen binaries in the build output; running on an OS/architecture without prebuilt native libs; a publish/deploy step that stripped unmanaged dependencies; corrupted native library files.","solutions":["Verify the freetype and stride_msdfgen native binaries exist next to the executable for the target platform/architecture (win-x64, linux-x64, etc.).","Rebuild/restore the Stride.Assets package so native dependencies are copied to the output directory.","Use the FreeType error code in the message to narrow the cause (e.g. 1 = cannot open resource).","Fix the deploy/publish step so unmanaged .dll/.so files are included; test on a clean machine to confirm."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// before importing, confirm the native libraries can be located on this machine\nNativeLibraryHelper.PreloadLibrary(\"freetype\", typeof(SignedDistanceFieldFontImporter));\nNativeLibraryHelper.PreloadLibrary(\"stride_msdfgen\", typeof(SignedDistanceFieldFontImporter));\n// if preload throws or silently fails on your platform, resolve the native deps first","typeGuard":"bool NativeFontDepsAvailable() =>\n    NativeLibrary.TryLoad(\"freetype\", out _) && NativeLibrary.TryLoad(\"stride_msdfgen\", out _);","tryCatchPattern":"try\n{\n    importer.Import(fontSource, characters, options);\n}\ncatch (InvalidOperationException ex) when (ex.Message.StartsWith(\"Failed to initialize FreeType library\"))\n{\n    logger.LogError(ex, \"Native FreeType failed to initialize. Check that freetype/stride_msdfgen native binaries for {Platform} are deployed.\", Environment.OSVersion);\n    throw; // do not retry: init failure is environmental, not transient\n}","preventionTips":["Verify native binaries (freetype, stride_msdfgen) are copied to the output for every target RID.","Include unmanaged .dll/.so files in publish/deploy packaging; do not strip them.","Smoke-test font asset compilation on a clean machine/CI image before release.","Keep managed Stride assemblies and native libraries at matching versions."],"tags":["native","freetype","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"}