What causes "Step '{step.Name}' depends on unknown step '{dependency}'" in microsoft/aspire?

Fix the dependency string to exactly match an existing step's Name (names are compared Ordinally, so casing matters)

microsoft/aspire · error · InvalidOperationException

Step ' ' depends on unknown step

Error message

Step '{step.Name}' depends on unknown step '{dependency}'

What it means

After collecting all step names, ValidateSteps verifies that every entry in a step's DependsOnSteps collection refers to a step that actually exists in the pipeline. A reference to a name that was never registered would make the dependency graph unschedulable, so an InvalidOperationException is thrown naming the depending step and the unknown dependency.

Solutions

Fix the dependency string to exactly match an existing step's Name (names are compared Ordinally, so casing matters)
Register the missing step that the dependency refers to
Make the dependent step's registration conditional on the same condition that gates the dependency's registration
If a package renamed a step, update to the new step name per that package's docs

Example fix

// before
pipeline.AddStep("publish").DependsOn("build-images");
// after (matching actual step name)
pipeline.AddStep("publish").DependsOn("build-image");

Defensive patterns

Strategy: validation

Validate before calling

var registered = pipeline.Steps.Select(s => s.Name).ToHashSet(StringComparer.Ordinal);
foreach (var step in pipeline.Steps)
    foreach (var dep in step.DependsOnSteps)
        if (!registered.Contains(dep))
            throw new InvalidOperationException($"Step '{step.Name}' references unknown dependency '{dep}'");

Try / catch

try { await pipeline.ExecuteAsync(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("depends on unknown step"))
{
    // ex.Message names both the step and the unknown dependency; fix the string
}

Prevention

Define step names as constants/shared fields so dependencies reference symbols, not raw strings
When renaming a step, grep for all DependsOn usages of the old name
Mirror registration conditions: gate dependent and dependency behind the same ExecutionContext check
Keep dependency wiring adjacent to the step registration it refers to

When it happens

Trigger: A step calls DependsOn("SomeName") (or populates DependsOnSteps) with a name that no registered step uses — typically a typo, a step that was removed/renamed, or a step belonging to a different pipeline. Also triggered when a step is conditionally registered but its dependents are registered unconditionally.

Common situations: Renaming a step without updating DependsOnSteps callers; upgrading an integration that renamed its internal step; misspelling the step name string; guard clauses (if (builder.ExecutionContext.IsRunMode)) that skip registering a step while other steps still depend on it.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/Pipelines/DistributedApplicationPipeline.cs:826

    {
        var stepNames = new HashSet<string>(StringComparer.Ordinal);

        foreach (var step in steps)
        {
            if (!stepNames.Add(step.Name))
            {
                throw new InvalidOperationException(
                    $"Duplicate step name: '{step.Name}'");
            }
        }

        foreach (var step in steps)
        {
            foreach (var dependency in step.DependsOnSteps)
            {
                if (!stepNames.Contains(dependency))
                {
                    throw new InvalidOperationException(
                        $"Step '{step.Name}' depends on unknown step '{dependency}'");
                }
            }

            foreach (var requiredBy in step.RequiredBySteps)
            {
                if (!stepNames.Contains(requiredBy))
                {
                    throw new InvalidOperationException(
                        $"Step '{step.Name}' is required by unknown step '{requiredBy}'");
                }
            }
        }
    }

    /// <summary>
    /// Executes pipeline steps by building a Task DAG where each step waits on its dependencies.
    /// Failed steps prevent dependent steps from executing, while independent steps continue running.

View on GitHub (pinned to 25830f84bd)