stride3d/stride · error · InvalidOperationException

Failed to initialize FreeType library

Error message

Failed to initialize FreeType library (error {err})

What it means

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.

Solutions

1. Ensure the freetype native binaries ship with your build for the target platform/architecture.
2. Install the system FreeType package (e.g. apt install libfreetype6) on Linux.
3. Confirm NativeLibraryHelper.PreloadLibrary("freetype") resolves the bundled library; check bitness (x86 vs x64).

try
{
    FreeTypeFontCompiler.Compile(fontAsset);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("FreeType library"))
{
    log.Error("Native FreeType failed to init; check platform native binaries.", ex);
}

When it happens

Trigger: 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.

Common situations: Missing native dependency on Linux/macOS (e.g. libfreetype not installed or wrong architecture); deploying without the native binaries; corrupted native library load.

Related errors

• Failed to load font ' ' (FreeType error )
• Failed to load glyph for character
• Failed to render glyph for character
• Could not locate native executable
• Could not locate native library

AI-assisted analysis of stride3d/stride@96fad776d2 (2026-09-14). Data as JSON: /api/errors/673fb9c7f86262be. Report an issue: GitHub.

Appendix: source

Thrown at sources/engine/Stride.Assets/SpriteFont/Compiler/FreeTypeFontImporter.cs:34

{
    // Rasterizes TrueType/OpenType glyphs using FreeType (pinned native binary in deps/).
    // This replaces the previous DirectWrite-based implementation so that static font
    // compilation is OS-independent and produces identical output across machines.
    internal unsafe class FreeTypeFontImporter : IFontImporter
    {
        public IEnumerable<Glyph> Glyphs { get; private set; }

        public float LineSpacing { get; private set; }

        public float BaseLine { get; private set; }

        public void Import(SpriteFontAsset options, List<char> characters)
        {
            NativeLibraryHelper.PreloadLibrary("freetype", typeof(FreeTypeFontImporter));

            int err = FreeTypeNative.FT_Init_FreeType(out var library);
            if (err != 0)
                throw new InvalidOperationException($"Failed to initialize FreeType library (error {err})");

            try
            {
                var fontPath = options.FontSource.GetFontPath();
                if (string.IsNullOrEmpty(fontPath) || !File.Exists(fontPath))
                    throw new FileNotFoundException($"Font file not found: {fontPath}");

                var fontData = File.ReadAllBytes(fontPath);
                var handle = GCHandle.Alloc(fontData, GCHandleType.Pinned);

                try
                {
                    FT_FaceRec* face;
                    fixed (byte* ptr = fontData)
                    {
                        err = FreeTypeNative.FT_New_Memory_Face(library, ptr, new CLong(fontData.Length), new CLong(0), out face);
                        if (err != 0)
                            throw new InvalidOperationException($"Failed to load font '{fontPath}' (FreeType error {err})");

View on GitHub (pinned to 96fad776d2)