stride3d/stride · error · ArgumentException

Tried to compile a dynamic sprite font with compiler for…

Error message

Tried to compile a dynamic sprite font with compiler for signed distance field fonts

What it means

SignedDistanceFieldFontCompiler.Compile only accepts SpriteFontAssets whose FontType is SignedDistanceFieldSpriteFontType. Any other FontType — including dynamic sprite font types — makes the cast fail and throws this ArgumentException. The compiler is SDF-specific and cannot process assets configured for other pipelines.

Solutions

Set the asset's FontType to SignedDistanceFieldSpriteFontType before calling the SDF compiler.
Route offline-rasterized assets to OfflineRasterizedFontCompiler — always use the compiler matching the FontType.
Add a FontType switch in build tooling to pick the correct compiler per asset.
Inspect the font asset definition and correct the FontType element.

Example fix

// before
SignedDistanceFieldFontCompiler.Compile(factory, rasterizedAsset); // throws
// after
switch (asset.FontType)
{
    case SignedDistanceFieldSpriteFontType: SignedDistanceFieldFontCompiler.Compile(factory, asset); break;
    case OfflineRasterizedSpriteFontType: OfflineRasterizedFontCompiler.Compile(factory, asset); break;
}

Defensive patterns

Strategy: type-guard

Validate before calling

if (fontAsset?.FontType is not SignedDistanceFieldSpriteFontType)
    throw new InvalidOperationException("SignedDistanceFieldFontCompiler requires a SignedDistanceFieldSpriteFontType asset");

Type guard

bool IsSdfFont(SpriteFontAsset asset) => asset?.FontType is SignedDistanceFieldSpriteFontType;

Try / catch

try
{
    var font = SignedDistanceFieldFontCompiler.Compile(factory, fontAsset);
}
catch (ArgumentException ex) when (ex.Message.Contains("dynamic sprite font"))
{
    // wrong pipeline: re-dispatch based on FontType
    font = CompileWithMatchingCompiler(factory, fontAsset);
}

Prevention

Route each font asset to the compiler matching its FontType.
Add a FontType switch at the single place build tooling dispatches to compilers.
Migrate legacy rasterized assets explicitly before using SDF compilation.
Review asset definitions after upgrades so FontType values remain valid.

When it happens

Trigger: Calling SignedDistanceFieldFontCompiler.Compile(fontFactory, fontAsset) where `fontAsset.FontType as SignedDistanceFieldSpriteFontType` returns null — e.g. an OfflineRasterizedSpriteFontType or dynamic font asset.

Common situations: Pointing the SDF compiler at a legacy rasterized font asset; build scripts that compile all fonts with one compiler regardless of FontType; pre-SDF assets whose FontType was never migrated.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

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

Appendix: source

Thrown at sources/engine/Stride.Assets/SpriteFont/Compiler/SignedDistanceFieldFontCompiler.cs:107

namespace Stride.Assets.SpriteFont.Compiler
{
    /// <summary>
    /// Main class used to compile a Font file XML file.
    /// </summary>
    public class SignedDistanceFieldFontCompiler
    {
        /// <summary>
        /// Compiles the specified font description into a <see cref="SignedDistanceFieldSpriteFont" /> object.
        /// </summary>
        /// <param name="fontFactory">The font factory used to create the fonts</param>
        /// <param name="fontAsset">The font description.</param>
        /// <returns>A SpriteFontData object.</returns>
        public static Graphics.SpriteFont Compile(IFontFactory fontFactory, SpriteFontAsset fontAsset)
        {
            var fontTypeSDF = fontAsset.FontType as SignedDistanceFieldSpriteFontType;
            if (fontTypeSDF == null)
                throw new ArgumentException("Tried to compile a dynamic sprite font with compiler for signed distance field fonts");

            float lineSpacing;
            float baseLine;

            var glyphs = ImportFont(fontAsset, out lineSpacing, out baseLine);

            Image<Rgba32> bitmap = GlyphPacker.ArrangeGlyphs(glyphs);

            return SignedDistanceFieldFontWriter.CreateSpriteFontData(fontFactory, fontAsset, glyphs, lineSpacing, baseLine, bitmap);
        }

        static Glyph[] ImportFont(SpriteFontAsset options, out float lineSpacing, out float baseLine)
        {
            // Which importer knows how to read this source font?
            IFontImporter importer;

            var sourceExtension = (Path.GetExtension(options.FontSource.GetFontPath()) ?? "").ToLowerInvariant();
            var bitmapFileExtensions = new List<string> { ".bmp", ".png", ".gif" };

View on GitHub (pinned to 96fad776d2)