stride3d/stride · error · InvalidOperationException

CommandList updating the staging resource has not been…

Error message

CommandList updating the staging resource has not been submitted

What it means

When mapping a Staging resource on Vulkan, Stride must wait for the command list that last updated it to be submitted. If another (or this) command list updated the resource but its submissions are pending and it is not this command list, Stride cannot safely wait and throws InvalidOperationException.

Solutions

Submit/flush the updating command list before mapping from a different command list (call Flush on the updater)
Update and map the staging resource from the same command list
Use GraphicsDevice.CommandList (the default) for staging uploads so updates and maps are ordered

Example fix

// before
stagingUpdaterCmdList.TextureData.SetData(...);
mainCmdList.MapSubResource(stagingTex, ...); // updater not submitted
// after
stagingUpdaterCmdList.Flush();
mainCmdList.MapSubResource(stagingTex, ...);

Defensive patterns

Strategy: try-catch

Validate before calling

if (stagingResource.UpdatingCommandList != null && stagingResource.UpdatingCommandList != currentCmdList)
    stagingResource.UpdatingCommandList.Flush();

Try / catch

try { cmdList.MapSubResource(staging, 0, MapMode.Read); } catch (InvalidOperationException ex) when (ex.Message.Contains("not been submitted")) { updatingList.Flush(); /* retry */ }

Prevention

Always Flush/Submit the command list that updated a staging resource before mapping it elsewhere
Use a single command list for staging updates and reads
Keep staging upload/read paths on GraphicsDevice.CommandList

When it happens

Trigger: Calling MapSubResource/Map on a Staging texture or buffer whose UpdatingCommandList differs from the calling command list and has not been submitted; interleaving updates from multiple command lists without submitting between them.

Common situations: Using two command lists to fill and then read one staging texture; forgetting to call GraphicsDevice.CommandList flush/submit before mapping from another list.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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

Appendix: source

Thrown at sources/engine/Stride.Graphics/Vulkan/CommandList.Vulkan.cs:1599

                if (
                    // used in command list which hasn't be submitted yet? (only valid if our own, checked later)
                    resource.UpdatingCommandList is not null
                    // updated in a previous command list which hasn't be finished yet
                    || (resource.CommandListFenceValue is not null && !GraphicsDevice.CommandListFence.IsFenceCompleteInternal(resource.CommandListFenceValue.Value)))
                {
                    // User told us not to wait, return right away
                    if (doNotWait)
                    {
                        return new MappedResource(resource, subResourceIndex, dataBox: default);
                    }

                    if (resource.UpdatingCommandList == this)
                        // Need to flush? (check if part of current command list)
                        // resource.CommandListFenceValue should be set after
                        FlushInternal(false);
                    else if (resource.UpdatingCommandList is not null)
                        // Another command list updated this resource, but it's not been submitted (otherwise it would be stored in resource.CommandListFenceValue
                        throw new InvalidOperationException("CommandList updating the staging resource has not been submitted");

                    if (resource.CommandListFenceValue is null)
                        throw new InvalidOperationException($"Invalid state for {resource.CommandListFenceValue}");

                    GraphicsDevice.CommandListFence.WaitForFenceCPUInternal(resource.CommandListFenceValue.Value);

                    // We're now up to date, remove command list fence value (if any)
                    resource.CommandListFenceValue = null;
                }
            }

            // Also make sure all copy queues are done
            // (important for all cases, since it uploads initial data and also set resource barrier)
            if (resource.CopyFenceValue.HasValue)
            {
                GraphicsDevice.CopyFence.WaitForFenceCPUInternal(resource.CopyFenceValue.Value);
                resource.CopyFenceValue = null;
            }

View on GitHub (pinned to 96fad776d2)