stride3d/stride · error · ArgumentException

Tried to compile a non-offline rasterized sprite font with…

Error message

Tried to compile a non-offline rasterized sprite font with the compiler for offline resterized fonts!

What it means

SpriteFontAssetCompiler.Prepare has two compile paths: runtime-rasterized fonts and offline-rasterized fonts. When the runtime path is not taken, it demands the FontType be an OfflineRasterizedSpriteFontType; anything else (e.g. RuntimeRasterizedSpriteFontType or SDF types) that reached this compiler is a programming/config error and throws ArgumentException.

Solutions

1. Open the spritefont asset in Game Studio and set the Font type to 'Offline Rasterized SpriteFont' to match this compiler.
2. Or set the asset to runtime rasterized so it is routed to RuntimeRasterizedFontCommand instead.
3. Compare the asset's serialized compiler/properties with a freshly created spritefont asset and fix the mismatch.

Example fix

// before (asset properties)
FontType: RuntimeRasterizedSpriteFontType { }
Compiler: OfflineRasterizedFontCompiler
// after
FontType: OfflineRasterizedSpriteFontType { CharacterSet: ... }

if (asset.FontType is not OfflineRasterizedSpriteFontType)
    throw new InvalidOperationException("Asset must use OfflineRasterizedSpriteFontType for this compiler");

bool IsOfflineRasterized(SpriteFontAsset a) => a.FontType is OfflineRasterizedSpriteFontType;

try
{
    PrepareOfflineFont(asset);
}
catch (ArgumentException ex) when (ex.Message.Contains("non-offline rasterized"))
{
    logger.Error($"{asset.Url}: FontType/compiler mismatch — set the font to offline rasterized or use the runtime compiler.");
}

When it happens

Trigger: An asset whose FontType is not OfflineRasterizedSpriteFontType was routed to the offline rasterized compiler — typically the spritefont asset sets IsRuntimeRasterizedSpriteFont false (or the processor selects this compiler) while FontType is a different concrete type.

Common situations: Hand-edited .sfz/.sdtpl asset files where the compiler property and FontType disagree; custom build scripts invoking the wrong compiler; upgrading Stride and asset properties being remapped inconsistently.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• A NodeIndex instance cannot be passed as the value of…
• Argument must be of type Angle.
• Behavior of type ' ' must be bound to objects of type ' '…
• Can not convert value to the required type
• Cannot copy data between Buffers and Textures.

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

Appendix: source

Thrown at sources/engine/Stride.Assets/SpriteFont/SpriteFontAssetCompiler.cs:65

                    if (fontPathOnDisk == null)
                    {
                        result.Error($"Runtime rasterized font compilation failed. Font {asset.FontSource.GetFontName()} was not found on this machine.");
                        result.BuildSteps = new AssetBuildStep(assetItem);
                        result.BuildSteps.Add(new FailedFontCommand());
                        return;
                    }

                    var fontImportLocation = FontHelper.GetFontPath(asset.FontSource.GetFontName(), asset.FontSource.Style);

                    result.BuildSteps = new AssetBuildStep(assetItem);
                    result.BuildSteps.Add(new ImportStreamCommand { SourcePath = fontPathOnDisk, Location = fontImportLocation });
                    result.BuildSteps.Add(new RuntimeRasterizedFontCommand(targetUrlInStorage, asset, assetItem.Package));
                }
                else
                {
                    var fontTypeStatic = asset.FontType as OfflineRasterizedSpriteFontType;
                    if (fontTypeStatic == null)
                        throw new ArgumentException("Tried to compile a non-offline rasterized sprite font with the compiler for offline resterized fonts!");

                    // copy the asset and transform the source and character set file path to absolute paths
                    var assetClone = AssetCloner.Clone(asset);
                    var assetDirectory = assetAbsolutePath.GetParent();
                    assetClone.FontSource = asset.FontSource;
                    fontTypeStatic.CharacterSet = !string.IsNullOrEmpty(fontTypeStatic.CharacterSet) ? UPath.Combine(assetDirectory, fontTypeStatic.CharacterSet): null;

                    result.BuildSteps = new AssetBuildStep(assetItem);
                    result.BuildSteps.Add(new OfflineRasterizedFontCommand(targetUrlInStorage, assetClone, colorSpace, assetItem.Package));
                }
        }

        internal class OfflineRasterizedFontCommand : AssetCommand<SpriteFontAsset>
        {
            private ColorSpace colorspace;

            public OfflineRasterizedFontCommand(string url, SpriteFontAsset description, ColorSpace colorspace, IAssetFinder assetFinder)
                : base(url, description, assetFinder)

View on GitHub (pinned to 96fad776d2)