{"record":{"id":"673fb9c7f86262be","repo":"stride3d/stride","slug":"failed-to-initialize-freetype-library-error-err","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/FreeTypeFontImporter.cs","lineNumber":34,"sourceCode":"{\n    // Rasterizes TrueType/OpenType glyphs using FreeType (pinned native binary in deps/).\n    // This replaces the previous DirectWrite-based implementation so that static font\n    // compilation is OS-independent and produces identical output across machines.\n    internal unsafe class FreeTypeFontImporter : IFontImporter\n    {\n        public IEnumerable<Glyph> Glyphs { get; private set; }\n\n        public float LineSpacing { get; private set; }\n\n        public float BaseLine { get; private set; }\n\n        public void Import(SpriteFontAsset options, List<char> characters)\n        {\n            NativeLibraryHelper.PreloadLibrary(\"freetype\", typeof(FreeTypeFontImporter));\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            try\n            {\n                var fontPath = options.FontSource.GetFontPath();\n                if (string.IsNullOrEmpty(fontPath) || !File.Exists(fontPath))\n                    throw new FileNotFoundException($\"Font file not found: {fontPath}\");\n\n                var fontData = File.ReadAllBytes(fontPath);\n                var handle = GCHandle.Alloc(fontData, GCHandleType.Pinned);\n\n                try\n                {\n                    FT_FaceRec* face;\n                    fixed (byte* ptr = fontData)\n                    {\n                        err = FreeTypeNative.FT_New_Memory_Face(library, ptr, new CLong(fontData.Length), new CLong(0), out face);\n                        if (err != 0)\n                            throw new InvalidOperationException($\"Failed to load font '{fontPath}' (FreeType error {err})\");","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/engine/Stride.Assets/SpriteFont/Compiler/FreeTypeFontImporter.cs#L16-L52","documentation":"FreeTypeFontImporter.Import preloads the native freetype library and calls FT_Init_FreeType; a non-zero FreeType error code aborts with this InvalidOperationException. It means the native FreeType engine could not be initialized, before any file is even read.","triggerScenarios":"FT_Init_FreeType returns an error code - typically because the native freetype native library failed to preload or the platform/runtime lacks the required native binaries.","commonSituations":"Missing native dependency on Linux/macOS (e.g. libfreetype not installed or wrong architecture); deploying without the native binaries; corrupted native library load.","solutions":["Ensure the freetype native binaries ship with your build for the target platform/architecture.","Install the system FreeType package (e.g. apt install libfreetype6) on Linux.","Confirm NativeLibraryHelper.PreloadLibrary(\"freetype\") resolves the bundled library; check bitness (x86 vs x64)."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try\n{\n    FreeTypeFontCompiler.Compile(fontAsset);\n}\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"FreeType library\"))\n{\n    log.Error(\"Native FreeType failed to init; check platform native binaries.\", ex);\n}","preventionTips":["Ship the correct freetype native binary for each RID.","Test font compilation on all target platforms/architectures in CI."],"tags":["fonts","native-interop","module-init-failed"],"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"}