stride3d/stride · error · InvalidOperationException

Failed to initialize FreeType library

Error message

Failed to initialize FreeType library (error {err})

What it means

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.

Solutions

1. Verify the freetype and stride_msdfgen native binaries exist next to the executable for the target platform/architecture (win-x64, linux-x64, etc.).
2. Rebuild/restore the Stride.Assets package so native dependencies are copied to the output directory.
3. Use the FreeType error code in the message to narrow the cause (e.g. 1 = cannot open resource).
4. Fix the deploy/publish step so unmanaged .dll/.so files are included; test on a clean machine to confirm.

// before importing, confirm the native libraries can be located on this machine
NativeLibraryHelper.PreloadLibrary("freetype", typeof(SignedDistanceFieldFontImporter));
NativeLibraryHelper.PreloadLibrary("stride_msdfgen", typeof(SignedDistanceFieldFontImporter));
// if preload throws or silently fails on your platform, resolve the native deps first

bool NativeFontDepsAvailable() =>
    NativeLibrary.TryLoad("freetype", out _) && NativeLibrary.TryLoad("stride_msdfgen", out _);

try
{
    importer.Import(fontSource, characters, options);
}
catch (InvalidOperationException ex) when (ex.Message.StartsWith("Failed to initialize FreeType library"))
{
    logger.LogError(ex, "Native FreeType failed to initialize. Check that freetype/stride_msdfgen native binaries for {Platform} are deployed.", Environment.OSVersion);
    throw; // do not retry: init failure is environmental, not transient
}

When it happens

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

Common situations: 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.

Related errors

• Failed to initialize FreeType library
• Failed to initialize msdfgen context
• Failed to initialize the audio native layer.
• Failed to create Celt custom mode.
• Failed to create an instance of the celt encoder/decoder.

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

Appendix: source

Thrown at sources/engine/Stride.Assets/SpriteFont/Compiler/SignedDistanceFieldFontImporter.cs:49

        public float BaseLine { get; private set; }

        private string fontSource;
        private IntPtr msdfgenContext;
        private IntPtr msdfgenFont;

        /// <inheritdoc/>
        public void Import(SpriteFontAsset options, List<char> characters)
        {
            fontSource = options.FontSource.GetFontPath();
            if (string.IsNullOrEmpty(fontSource))
                return;

            NativeLibraryHelper.PreloadLibrary("freetype", typeof(SignedDistanceFieldFontImporter));
            NativeLibraryHelper.PreloadLibrary("stride_msdfgen", typeof(SignedDistanceFieldFontImporter));

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

            msdfgenContext = MsdfgenNative.msdfgenContextCreate();
            if (msdfgenContext == IntPtr.Zero)
            {
                FreeTypeNative.FT_Done_FreeType(library);
                throw new InvalidOperationException("Failed to initialize msdfgen context");
            }

            msdfgenFont = MsdfgenNative.msdfgenLoadFont(msdfgenContext, fontSource);
            if (msdfgenFont == IntPtr.Zero)
            {
                MsdfgenNative.msdfgenContextDestroy(msdfgenContext);
                msdfgenContext = IntPtr.Zero;
                FreeTypeNative.FT_Done_FreeType(library);
                throw new AssetException($"Failed to load font '{fontSource}' into msdfgen.");
            }

            try

View on GitHub (pinned to 96fad776d2)