microsoft/aspire · error · InvalidOperationException

Step ' ' not found in pipeline. Available steps

Error message

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

What it means

The list-steps RPC request specified a pipeline Step name that does not exist among the resolved pipeline steps, so transitive dependency computation cannot proceed. The message lists all valid step names to help correct the request.

Solutions

Use one of the step names listed in the error's 'Available steps' portion.
Run GetPipelineStepsAsync without request.Step (or `aspire` list-steps) to enumerate valid names.
Check spelling and casing exactly; matching is case-sensitive (StringComparer.Ordinal).
If the step should exist, ensure the code adding the pipeline step annotation/registration runs before resolution.

Example fix

// before
await rpc.GetPipelineStepsAsync(new GetPipelineStepsRequest { Step = "build-containers" });
// after
await rpc.GetPipelineStepsAsync(new GetPipelineStepsRequest { Step = "build-container-images" }); // name from Available steps list

Defensive patterns

Strategy: validation

Validate before calling

var allSteps = await rpc.GetPipelineStepsAsync(new GetPipelineStepsRequest());
if (!allSteps.Steps.Any(s => s.Name == targetStep)) throw new ArgumentException($"Step '{targetStep}' not found. Valid: {string.Join(", ", allSteps.Steps.Select(s => s.Name))}");

Try / catch

try { await rpc.GetPipelineStepsAsync(new GetPipelineStepsRequest { Step = stepName }); }
catch (InvalidOperationException ex) when (ex.Message.StartsWith("Step '")) { logger.LogError(ex, "Unknown pipeline step '{Step}'", stepName); }

Prevention

Enumerate steps first with no Step filter before targeting one.
Copy step names exactly — lookup is case-sensitive (Ordinal).
Re-check step names after AppHost model changes or Aspire upgrades.

When it happens

Trigger: Calling GetPipelineStepsAsync (or the CLI equivalent, e.g. `aspire publish --step X` / list-steps targeting a step) with request.Step set to a name not present in the resolved step set — typos, renamed steps, or steps contributed by annotations that are not registered.

Common situations: Typo or stale step name in scripts/automation after the app model changed; targeting a step that only exists in another AppHost; case-sensitivity mismatch (lookup uses Ordinal comparison); step removed in an Aspire version upgrade.

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

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

Appendix: source

Thrown at src/Aspire.Hosting/Backchannel/AppHostRpcTarget.cs:318

        var model = serviceProvider.GetRequiredService<DistributedApplicationModel>();
        var executionContext = serviceProvider.GetRequiredService<DistributedApplicationExecutionContext>();

        var pipelineContext = new PipelineContext(model, executionContext, serviceProvider, logger, cancellationToken);

        var resolvedSteps = await pipeline.ResolveStepsAsync(pipelineContext).ConfigureAwait(false);

        // If a target step is specified, filter to its transitive dependencies
        if (!string.IsNullOrEmpty(request?.Step))
        {
            var stepsByName = resolvedSteps.ToDictionary(s => s.Name, StringComparer.Ordinal);
            if (stepsByName.TryGetValue(request.Step, out var targetStep))
            {
                resolvedSteps = DistributedApplicationPipeline.ComputeTransitiveDependencies(targetStep, stepsByName);
            }
            else
            {
                var availableSteps = string.Join(", ", resolvedSteps.Select(s => $"'{s.Name}'"));
                throw new InvalidOperationException(
                    $"Step '{request.Step}' not found in pipeline. Available steps: {availableSteps}");
            }
        }

        var orderedSteps = DistributedApplicationPipeline.GetTopologicalOrder(resolvedSteps);
#pragma warning restore ASPIREPIPELINES001

        return new GetPipelineStepsResponse
        {
            Steps = orderedSteps.Select(step => new PipelineStepInfo
            {
                Name = step.Name,
                Description = step.Description,
                DependsOn = [.. step.DependsOnSteps],
                Tags = [.. step.Tags],
                ResourceName = step.Resource?.Name
            }).ToArray()
        };

View on GitHub (pinned to 25830f84bd)