stride3d/stride · error · KeyNotFoundException

spriteName

Error message

spriteName

What it means

SpriteSheet.FindImageIndex throws KeyNotFoundException wrapping the requested spriteName when no Sprite in the sheet has that Name. The exception message is the missing name itself. It is thrown by the FindImageIndex helper used by the SpriteSheet constructor and Create factory methods, so a bad name aborts sheet creation/lookup.

Solutions

1. Verify the exact sprite name (case-sensitive) against the sprites defined in the SpriteSheet asset
2. Iterate sheet.Sprites and log available Names to find the correct one
3. Use an index-based lookup or resolve the name once and cache the index
4. Add a Contains/name check before calling FindImageIndex if the name is user-supplied

Example fix

// before
int idx = spriteSheet.FindImageIndex("player_idle");
// after
int idx = spriteSheet.FindImageIndex("PlayerIdle"); // exact name from the sheet asset
// or defensively:
int idx = spriteSheet.Sprites.FindIndex(s => s.Name == name);
if (idx < 0) { /* handle missing sprite */ }

int idx = spriteSheet.Sprites.FindIndex(s => s.Name == spriteName);
if (idx < 0) throw new InvalidOperationException($"Sprite '{spriteName}' not in sheet; available: {string.Join(",", spriteSheet.Sprites.Select(s => s.Name))}");

static bool HasSprite(SpriteSheet sheet, string name) => sheet?.Sprites?.Any(s => s.Name == name) == true;

try { idx = spriteSheet.FindImageIndex(name); }
catch (KeyNotFoundException e) { Log.Warning($"Sprite '{e.Message}' missing from sheet"); idx = fallbackIndex; }

When it happens

Trigger: Passing a sprite name to SpriteSheet.FindImageIndex (directly or via SpriteSheet.Create/constructor) that does not match any Sprites[i].Name exactly — case-sensitive full-match comparison.

Common situations: Typo or wrong casing in the sprite name string; sprite removed or renamed in the image atlas but the code still references the old name; querying a different sheet than intended; localized/auto-generated sprite names changing between asset rebuilds.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• spriteBatch
• Tag not found in template generator parameters
• A file path cannot end with with directory char '\' or '/'…
• A Gear constraint requires two rigidbodies.
• A MaterialPass can only belong to a single Material

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

Appendix: source

Thrown at sources/engine/Stride.Graphics/SpriteSheet.cs:43

        /// <summary>
        /// Find the index of a sprite in the group using its name.
        /// </summary>
        /// <param name="spriteName">The name of the sprite</param>
        /// <returns>The index value</returns>
        /// <remarks>If two sprites have the provided name then the first sprite found is returned</remarks>
        /// <exception cref="KeyNotFoundException">No sprite in the group have the given name</exception>
        public int FindImageIndex(string spriteName)
        {
            if (Sprites != null)
            {
                for (int i = 0; i < Sprites.Count; i++)
                {
                    if (Sprites[i].Name == spriteName)
                        return i;
                }
            }

            throw new KeyNotFoundException(spriteName);
        }

        /// <summary>
        /// Gets or sets the image of the group at <paramref name="index"/>.
        /// </summary>
        /// <param name="index">The image index</param>
        /// <returns>The image</returns>
        public Sprite this[int index]
        {
            get { return Sprites[index]; }
            set { Sprites[index] = value; }
        }

        /// <summary>
        /// Gets or sets the image of the group having the provided <paramref name="name"/>.
        /// </summary>
        /// <param name="name">The name of the image</param>
        /// <returns>The image</returns>

View on GitHub (pinned to 96fad776d2)