What causes "Failed to parse SpriteStudio cell textures." in stride3d/stride?

Verify asset.Source points to an existing, readable SpriteStudio cell map file and that referenced textures are present next to it

stride3d/stride · error · Exception

Failed to parse SpriteStudio cell textures.

Error message

Failed to parse SpriteStudio cell textures.

What it means

During asset compilation, SpriteStudioModelAssetCompiler.Prepare parses the SpriteStudio cell map XML via SpriteStudioXmlImport.ParseCellMaps to extract cell definitions and texture references. If parsing fails (returns false) — malformed XML, missing required nodes, or a missing/unreadable source file — the compiler throws a generic Exception since the asset cannot be built.

Solutions

Verify asset.Source points to an existing, readable SpriteStudio cell map file and that referenced textures are present next to it
Re-export the cell map from SpriteStudio in a format/version supported by the importer (check the exporter version)
Validate the XML structure (cellmap root, cell entries, img attributes) — fix or remove hand edits
Enable asset-compiler logs for SpriteStudioXmlImport to see the precise parse failure before the generic exception

Example fix

// before (broken XML: missing img attribute)
<cell name="hero" x="0" y="0"/> <!-- parse fails -->
// after (valid SpriteStudio cellmap)
<cellmap>
  <img name="hero.png" width="256" height="256"/>
  <cell name="hero" x="0" y="0" width="64" height="64"/>
</cellmap>

Defensive patterns

Strategy: validation

Validate before calling

if (!File.Exists(asset.Source))
    throw new BuildException($"SpriteStudio cell map not found: {asset.Source}");
// plus XSD/structure check for <cellmap>/<cell>/<img> before compiling

Try / catch

try
{
    ParseCellMaps(asset.Source, images, cells);
}
catch (Exception ex)
{
    Logger.Error($"Cell map parse failed: {ex.Message}");
    throw;
}

Prevention

Validate cell map XML structure at export time
Keep referenced textures next to the cell map and use relative paths
Pin a supported SpriteStudio exporter version

When it happens

Trigger: ParseCellMaps returning false for asset.Source: the .ssp/cell map file doesn't exist at the source path, the XML is not a valid SpriteStudio cell map (missing <cellmap>/<cell> or <img> elements), or the XML fails to load (encoding/schema issues).

Common situations: Exporting from SpriteStudio with an unsupported version/format; forgetting to include referenced texture files next to the cell map; renaming assets after export so paths in the XML break; hand-edited XML with schema errors.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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

Appendix: source

Thrown at sources/engine/Stride.SpriteStudio.Offline/SpriteStudioModelAssetCompiler.cs:34

using Stride.Core.Assets;
using Stride.Core.Mathematics;
using Stride.Core.Serialization.Contents;

namespace Stride.SpriteStudio.Offline
{
    [AssetCompiler(typeof(SpriteStudioModelAsset), typeof(AssetCompilationContext))]
    internal class SpriteStudioModelAssetCompiler : AssetCompilerBase
    {
        protected override void Prepare(AssetCompilerContext context, AssetItem assetItem, string targetUrlInStorage, AssetCompilerResult result)
        {
            var asset = (SpriteStudioModelAsset)assetItem.Asset;
            var gameSettingsAsset = context.GetGameSettingsAsset();
            var renderingSettings = gameSettingsAsset.GetOrCreate<RenderingSettings>();
            var colorSpace = renderingSettings.ColorSpace;

            var cells = new List<SpriteStudioCell>();
            var images = new List<UFile>();
            if (!SpriteStudioXmlImport.ParseCellMaps(asset.Source, images, cells)) throw new Exception("Failed to parse SpriteStudio cell textures.");

            var texIndex = 0;
            asset.BuildTextures.Clear();
            foreach (var texture in images)
            {
                var textureAsset = new TextureAsset
                {
                    Id = AssetId.Empty, // CAUTION: It is important to use an empty GUID here, as we don't want the command to be rebuilt (by default, a new asset is creating a new guid)
                    IsStreamable = false,
                    IsCompressed = false,
                    GenerateMipmaps = true,
                    Type = new ColorTextureType
                    {
                        Alpha = AlphaFormat.Auto,
                        PremultiplyAlpha = true,
                        UseSRgbSampling = true,
                    }
                };

View on GitHub (pinned to 96fad776d2)