{"record":{"id":"e33586f9146222d8","repo":"stride3d/stride","slug":"failed-to-initialize-freetype-library-error-err-fontmanager","errorCode":null,"errorMessage":"Failed to initialize FreeType library (error {err})","messagePattern":"Failed to initialize FreeType library \\(error (.+?)\\)","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"critical","filePath":"sources/engine/Stride.Graphics/Font/FontManager.cs","lineNumber":95,"sourceCode":"        /// Note that we cannot just increase space taken in the bin packer because artifacts with old/previous characters may happen.\n        /// </remarks>\n        /// </summary>\n        private Int2 borderSize = Int2.One;\n\n        /// <summary>\n        /// Create an empty register.\n        /// </summary>\n        public FontManager(IDatabaseFileProviderService fileProviderService)\n        {\n            contentManager = new ContentManager(fileProviderService);\n\n            // Preload proper freetype native library (depending on CPU type).\n            NativeLibraryHelper.PreloadLibrary(\"freetype\", typeof(FontManager));\n\n            // Initialize FreeType library\n            int err = FreeTypeNative.FT_Init_FreeType(out freetypeLibrary);\n            if (err != 0)\n                throw new InvalidOperationException($\"Failed to initialize FreeType library (error {err})\");\n\n            // launch the thumbnail builder thread\n            bitmapBuilderThread = new Thread(SafeAction.Wrap(BuildBitmapThread)) { IsBackground = true, Name = \"Bitmap Builder thread\" };\n            bitmapBuilderThread.Start();\n        }\n\n        /// <summary>\n        /// Start the generation of the specified character's bitmap.\n        /// </summary>\n        /// <remarks>Does nothing if the bitmap already exists or its generation is already pending.</remarks>\n        /// <param name=\"characterSpecification\">The character we want the bitmap of</param>\n        /// <param name=\"synchronously\">Indicate if the generation of the bitmap must by done synchronously or asynchronously</param>\n        public void GenerateBitmap(CharacterSpecification characterSpecification, bool synchronously)\n        {\n            // Synchronous: render glyph info and bitmap immediately on the calling thread.\n            // Hold dataStructuresLock so we never render the same glyph concurrently with the\n            // builder thread (whichever takes the lock first renders it, the other skips), which\n            // keeps ResetGlyph from clobbering freshly written glyph data.","sourceCodeStart":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/engine/Stride.Graphics/Font/FontManager.cs#L77-L113","documentation":"The FontManager constructor calls FT_Init_FreeType and throws InvalidOperationException when FreeType returns a nonzero error code. This means the native FreeType library loaded but its global initialization failed, so no font work can be done in this process.","triggerScenarios":"Creating a new FontManager (directly or via FontSystem.Load) on a machine where FT_Init_FreeType fails, usually due to a broken/mismatched native freetype binary or exhausted memory.","commonSituations":"Missing or wrong-architecture native freetype.dll/libfreetype.so after deploying without the native assets; corrupted native library; low-memory environments (CI containers) where FreeType cannot allocate its internal structures.","solutions":["Verify the correct native freetype library for the platform/CPU is deployed next to the app (NativeLibraryHelper.PreloadLibrary resolves it)","Re-copy or reinstall the Stride native dependencies so the freetype binary is not corrupted","Check available memory; FreeType init allocates internal state and fails under memory pressure","Log the numeric FreeType error code and compare with FreeType docs (FT_Err_*) to identify the cause"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Cannot pre-validate native init; ensure native libs deployed:\n// verify 'freetype' native binary exists for the current RuntimeInformation.ProcessArchitecture","typeGuard":null,"tryCatchPattern":"try { var fm = new FontManager(fileProvider); }\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"FreeType\"))\n{\n    log.Fatal(\"FreeType init failed; check native freetype deployment\", ex);\n    throw;\n}","preventionTips":["Deploy all Stride native dependencies per-platform and verify after build","Test font initialization in CI containers to catch missing native libs early","Monitor memory; FreeType init fails under severe memory pressure"],"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"}