{"record":{"id":"e882f69b427ac85a","repo":"stride3d/stride","slug":"failed-to-load-font-fontpath-freetype-error-err","errorCode":null,"errorMessage":"Failed to load font '{fontPath}' (FreeType error {err})","messagePattern":"Failed to load font '(.+?)' \\(FreeType error (.+?)\\)","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"sources/engine/Stride.Assets/SpriteFont/Compiler/FreeTypeFontImporter.cs","lineNumber":52,"sourceCode":"                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})\");\n                    }\n\n                    try\n                    {\n                        var fontSize = options.FontType.Size;\n\n                        // Set font size: 26.6 fixed-point, 72 dpi so size is in pixels\n                        var charSize = new CLong((int)(fontSize * 64));\n                        FreeTypeNative.FT_Set_Char_Size(face, charSize, charSize, 72, 72);\n\n                        // Compute line spacing and baseline using FreeType metrics\n                        // These are in font units — convert to pixels\n                        float unitsToPixels = fontSize / face->units_per_EM;\n                        var lineGap = (face->height - face->ascender + face->descender) * options.LineGapFactor;\n                        LineSpacing = (lineGap + face->ascender - face->descender) * unitsToPixels;\n                        BaseLine = (lineGap * options.LineGapBaseLineFactor + face->ascender) * unitsToPixels;\n\n                        var glyphList = new List<Glyph>();","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/engine/Stride.Assets/SpriteFont/Compiler/FreeTypeFontImporter.cs#L34-L70","documentation":"FreeTypeFontImporter.Import loads the font bytes with FT_New_Memory_Face; if FreeType returns a non-zero error code the importer throws this InvalidOperationException. It means FreeType could not parse the font data as a valid font face (the file existed but is invalid/unsupported).","triggerScenarios":"Passing a corrupt, truncated, or non-font file (wrong format, DRM-protected font, HTML error page saved as .ttf) to FT_New_Memory_Face during sprite font compilation.","commonSituations":"Misnamed file extensions (e.g. an OTF variable font variant unsupported by the bundled FreeType); partial downloads; wrong file selected in the FontSource picker.","solutions":["Verify the font file is a valid, uncorrupted TTF/OTF (open it in a font viewer).","Re-download or re-export the font file; avoid truncated copies.","Try a different static font file; some variable/restricted fonts fail to load."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"var bytes = File.ReadAllBytes(fontPath);\nif (bytes.Length < 4 ||\n    !(bytes[0] == 0x00 && bytes[1] == 0x01 && bytes[2] == 0x00 && bytes[3] == 0x00) &&\n    !System.Text.Encoding.ASCII.GetString(bytes, 0, 4).Contains(\"OTTO\"))\n    throw new InvalidDataException(\"Not a valid TTF/OTF file\");","typeGuard":null,"tryCatchPattern":"catch (InvalidOperationException ex) when (ex.Message.Contains(\"FreeType error\")) { log.Error($\"Invalid font data: {ex.Message}\"); }","preventionTips":["Verify fonts open in a font viewer before adding them to assets.","Avoid truncated downloads; checksum font files."],"tags":["fonts","native-interop","invalid-argument-value"],"backgroundTag":"invalid-argument-value","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"}