stride3d/stride · error · ArgumentNullException

spriteBatch

Error message

spriteBatch

What it means

The Sprite.Draw extension method throws ArgumentNullException when the provided spriteBatch is null (the XML docs even label it ArgumentOutOfRangeException, but the code throws ArgumentNullException). The sprite needs a batch to record its draw command; without one nothing can be rendered.

Solutions

1. Pass a valid SpriteBatch instance (typically resolved via Services.GetService<SpriteBatch>() or the render system's batch)
2. Guard the call: if (spriteBatch != null) sprite.Draw(spriteBatch, ...)
3. Move the draw call after batch initialization (e.g. out of LoadContent into Draw phase)
4. Check component initialization order so the batch exists before the sprite draws

Example fix

// before
sprite.Draw(spriteBatch, Position); // spriteBatch may be null
// after
spriteBatch = Services.GetSafeServiceAs<SpriteBatch>();
if (spriteBatch != null)
    sprite.Draw(spriteBatch, Position);

if (spriteBatch == null) spriteBatch = Services.GetSafeServiceAs<SpriteBatch>();
if (spriteBatch != null) sprite.Draw(spriteBatch, position);

static bool CanDraw(Sprite sprite, SpriteBatch batch) => batch != null && sprite?.Texture != null;

try { sprite.Draw(spriteBatch, pos); }
catch (ArgumentNullException) { Log.Warning("Sprite draw skipped: no SpriteBatch resolved"); }

When it happens

Trigger: Calling sprite.Draw(null, position, ...) — usually a SpriteBatch field that was not resolved from a service/scene, or drawing before the render system created the batch.

Common situations: Forgetting to inject/resolve the SpriteBatch from the game's Services; calling Draw in a component before base.Initialize created the batch; ordering issue where the UI system is torn down before a late draw call.

Related errors

• graphicsDevice
• resource
• text
• texture
• [ ] cannot be null in

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

Appendix: source

Thrown at sources/engine/Stride.Graphics/SpriteExtensions.cs:49

        /// <summary>
        /// Draw a sprite using a sprite batch.
        /// </summary>
        /// <param name="sprite">The sprite</param>
        /// <param name="spriteBatch">The sprite batch used to draw the sprite.</param>
        /// <param name="position">The position to which draw the sprite</param>
        /// <param name="color">The color to use to draw the sprite</param>
        /// <param name="rotation">The rotation to apply on the sprite</param>
        /// <param name="scales">The scale factors to apply on the sprite</param>
        /// <param name="depthLayer">The depth layer to which draw the sprite</param>
        /// <param name="spriteEffects">The sprite effect to apply on the sprite</param>
        /// <remarks>This function must be called between the <see cref="SpriteBatch.Begin"/>
        /// and `SpriteBatch.End()` calls of the provided <paramref name="spriteBatch"/></remarks>
        /// <exception cref="ArgumentException">The provided frame index is not valid.</exception>
        /// <exception cref="ArgumentOutOfRangeException">The provided spriteBatch is null</exception>
        public static void Draw(this Sprite sprite, SpriteBatch spriteBatch, Vector2 position, Color color, Vector2 scales, float rotation = 0f, float depthLayer = 0, SpriteEffects spriteEffects = SpriteEffects.None)
        {
            if (spriteBatch == null) throw new ArgumentNullException("spriteBatch");

            if (sprite.Texture == null)
                return;

            spriteBatch.Draw(sprite.Texture, position, sprite.Region, color, rotation, sprite.Center, scales, spriteEffects, sprite.Orientation, depthLayer);
        }

        /// <summary>
        /// Draw a sprite in the 3D world using the provided 3D sprite batch, world matrix and color.
        /// </summary>
        /// <param name="sprite">The sprite</param>
        /// <param name="spriteBatch">The sprite batch used to draw the sprite.</param>
        /// <param name="worldMatrix">The world matrix of the sprite</param>
        /// <param name="color">The color to apply on the sprite</param>
        /// <remarks>This function must be called between the <see cref="SpriteBatch.Begin"/>
        /// and `SpriteBatch.End()` calls of the provided <paramref name="spriteBatch"/></remarks>
        /// <exception cref="ArgumentException">The provided frame index is not valid.</exception>
        /// <exception cref="ArgumentOutOfRangeException">The provided spriteBatch is null</exception>

View on GitHub (pinned to 96fad776d2)