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

GetCharactersToImport in OfflineRasterizedFontCompiler only accepts a SpriteFontAsset whose FontType is OfflineRasterizedSpriteFontType. Passing an asset configured for another pipeline (dynamic sprite font or SDF) makes the cast fail and throws this ArgumentException. Despite the message text mentioning signed distance field fonts, the real condition is simply: the FontType is not the offline rasterized type.

Solutions

Set the asset's FontType to OfflineRasterizedSpriteFontType (with a CharacterSet file or character regions) before compiling offline.
If you want a dynamic font, do not run it through OfflineRasterizedFontCompiler — dynamic fonts are built at runtime, not by this asset compiler.
Audit the asset definition and make sure the FontType element matches the compiler being invoked.
In tooling code, type-check `asset.FontType is OfflineRasterizedSpriteFontType` before calling.

Example fix

// before
asset.FontType = new DynamicSpriteFontType();
var chars = OfflineRasterizedFontCompiler.GetCharactersToImport(asset);
// after
asset.FontType = new OfflineRasterizedSpriteFontType { CharacterSet = "charset.txt" };
var chars = OfflineRasterizedFontCompiler.GetCharactersToImport(asset);

Defensive patterns

Strategy: type-guard

Validate before calling

if (asset?.FontType is not OfflineRasterizedSpriteFontType)
    throw new InvalidOperationException("OfflineRasterizedFontCompiler requires an OfflineRasterizedSpriteFontType asset");

Type guard

bool CanCompileOffline(SpriteFontAsset asset) => asset?.FontType is OfflineRasterizedSpriteFontType;

Try / catch

try
{
    var chars = OfflineRasterizedFontCompiler.GetCharactersToImport(asset);
}
catch (ArgumentException ex) when (ex.Message.Contains("dynamic sprite font"))
{
    logger.LogWarning("Asset {Name} is not offline-rasterizable; routing to dynamic pipeline", asset.Name);
    // build/compile the font at runtime instead
}

Prevention

Match compiler to FontType: offline compiler for OfflineRasterizedSpriteFontType, SDF compiler for SDF types.
Never route dynamic (runtime) fonts through offline asset compilers.
Use a switch on FontType in build tooling instead of assuming one compiler fits all.
Keep font asset templates consistent so FontType is not accidentally changed.

When it happens

Trigger: Invoking OfflineRasterizedFontCompiler.GetCharactersToImport or Compile with a SpriteFontAsset whose FontType is a dynamic sprite font type or SignedDistanceFieldSpriteFontType instead of OfflineRasterizedSpriteFontType.

Common situations: Mixing dynamic and static (offline-rasterized) font assets in build scripts; an asset whose FontType was changed to dynamic but still routed through the offline compiler; programmatic font asset generation assigning the wrong FontType subclass.

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/cdc0ba4b7b46d41c. Report an issue: GitHub.

Appendix: source

Thrown at sources/engine/Stride.Assets/SpriteFont/Compiler/OfflineRasterizedFontCompiler.cs:204

                        break;
                    }
                }
                if (!defaultCharacterFound)
                {
                    throw new InvalidOperationException("The specified DefaultCharacter is not part of this font.");
                }
            }

            return glyphs.ToArray();
        }

        public static List<char> GetCharactersToImport(SpriteFontAsset asset)
        {
            var characters = new List<char>();

            var fontTypeStatic = asset.FontType as OfflineRasterizedSpriteFontType;
            if (fontTypeStatic == null)
                throw new ArgumentException("Tried to compile a dynamic sprite font with compiler for signed distance field fonts");

            // extract the list from the provided file if it exits
            if (File.Exists(fontTypeStatic.CharacterSet))
            {
                string text;
                using (var streamReader = new StreamReader(fontTypeStatic.CharacterSet, Encoding.UTF8))
                    text = streamReader.ReadToEnd();
                characters.AddRange(text);
            }

            // add character coming from character ranges
            characters.AddRange(CharacterRegion.Flatten(fontTypeStatic.CharacterRegions));

            // remove duplicated characters
            characters = characters.Distinct().ToList();

            return characters;
        }

View on GitHub (pinned to 96fad776d2)