microsoft/aspire · error · InvalidOperationException

Step ' ' not found in pipeline. Available steps

Error message

Step '{stepName}' not found in pipeline. Available steps: {availableSteps}

What it means

WithFinalAction looks up a pipeline step by name and throws InvalidOperationException when no step with that name exists, listing all available step names. It is an eager validation that the requested step is part of the pipeline's model at configuration time.

Solutions

1. Copy one of the step names exactly from the 'Available steps' list in the message (matching is case-sensitive).
2. Ensure WithFinalAction is applied after the target step has been added to the pipeline.
3. Check the Aspire version for renames of built-in step names.

Example fix

// before
pipeline.WithFinalAction("Build-Container-Images", action);
// after: use an exact name from the available-steps list
pipeline.WithFinalAction("build-container-images", action);

// Verify the step exists before attaching a final action
var stepNames = pipeline.Model.Steps.Select(s => s.Name).ToHashSet(StringComparer.Ordinal);
if (!stepNames.Contains(stepName))
{
    throw new ArgumentException($"Unknown step '{stepName}'. Available: {string.Join(", ", stepNames)}");
}

try { pipeline.WithFinalAction(stepName, action); }
catch (InvalidOperationException ex) when (ex.Message.Contains("not found in pipeline"))
{
    logger.LogError(ex, "Check step name against available steps");
}

When it happens

Trigger: Calling pipeline.WithFinalAction("StepName", action) where StepName does not match any step in context.Steps — typically a typo or a step added later than the extension's configuration callback runs.

Common situations: Misspelled step name (case-sensitive comparison); attaching a final action to a step from a different pipeline version or feature-gated source; referencing an internal step name that was renamed in a newer Aspire version.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

• Step ' ' not found in pipeline. Available steps
• A purge task with the name
• A step with the name
• ASPIRERADIUS049
• ASPIRERADIUS083

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/744afad27d53a8f5. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting/Pipelines/DistributedApplicationPipelineExtensions.cs:50

    /// final actions are not invoked.
    /// </remarks>
    [AspireExportIgnore(Reason = "Delegate callbacks are not ATS-compatible.")]
    public static IDistributedApplicationPipeline WithFinalAction(
        this IDistributedApplicationPipeline pipeline,
        string stepName,
        Func<PipelineStepContext, Task> action)
    {
        ArgumentNullException.ThrowIfNull(pipeline);
        ArgumentException.ThrowIfNullOrEmpty(stepName);
        ArgumentNullException.ThrowIfNull(action);

        pipeline.AddPipelineConfiguration(context =>
        {
            var step = context.Steps.FirstOrDefault(candidate => candidate.Name == stepName);
            if (step is null)
            {
                var availableSteps = string.Join(", ", context.Steps.Select(candidate => $"'{candidate.Name}'"));
                throw new InvalidOperationException(
                    $"Step '{stepName}' not found in pipeline. Available steps: {availableSteps}");
            }

            step.AddFinalAction(action);
            return Task.CompletedTask;
        });

        return pipeline;
    }

    /// <summary>
    /// Disables the publish and deploy validation that requires build-only containers to be consumed by another resource.
    /// </summary>
    /// <param name="pipeline">The distributed application pipeline.</param>
    /// <returns>The distributed application pipeline for chaining.</returns>
    /// <remarks>
    /// This is an application-wide escape hatch for scenarios where the build-only container validation is too restrictive
    /// for a particular app. Prefer wiring build-only containers through <c>PublishWithContainerFiles</c> or

View on GitHub (pinned to 25830f84bd)