microsoft/aspire · error

Azure environment resource required by AKS environment

Error message

Azure environment resource required by AKS environment '{Name}' was not found.

What it means

When the AKS environment runs its destroy-related steps, it depends on the single AzureEnvironmentResource in the application model, which owns the Azure provisioning/deployment state. If no such resource exists in the model, Aspire cannot find the Azure deployment scope or the destroy pipeline, so it throws. Every AKS environment is expected to be paired with exactly one Azure environment resource.

Solutions

1. Add the Azure environment resource to the AppHost (e.g. builder.AddAzureEnvironment(...)) alongside the AKS environment.
2. Remove the conditional guard that omits AddAzureEnvironment in the execution mode being run.
3. Ensure exactly one AzureEnvironmentResource is registered - duplicates would also break the SingleOrDefault contract.
4. Compare against a working AppHost sample to confirm the required resource pairing.

Example fix

// before
var aks = builder.AddAzureKubernetesEnvironment("aks");
// (no AddAzureEnvironment anywhere)

// after
builder.AddAzureEnvironment("azure");
var aks = builder.AddAzureKubernetesEnvironment("aks");

var azureEnv = appModel.Resources.OfType<AzureEnvironmentResource>().SingleOrDefault();
if (azureEnv is null)
    throw new InvalidOperationException("AppHost must call AddAzureEnvironment before using an AKS environment.");

bool HasAzureEnvironment(Aspire.Hosting.ApplicationModel.IResource model) =>
    model.Resources.OfType<AzureEnvironmentResource>().Any();

When it happens

Trigger: Executing the AKS environment's build/destroy steps when the application model contains zero (or the SingleOrDefault path cannot yield exactly one) AzureEnvironmentResource - e.g. the Azure environment was removed from the AppHost, added conditionally behind a flag, or the AKS resource was constructed in an app model without its Azure counterpart.

Common situations: Refactoring the AppHost to use an existing-resource-only setup and dropping AddAzureEnvironment; a `if (builder.ExecutionContext.IsPublishMode)` guard that skips adding the Azure environment; copying an AKS environment into a different AppHost that lacks the Azure pairing.

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

• az aks get-credentials failed
• az resource list failed
• az resource list failed while checking AKS cluster existence
• Azure destroy step for environment
• AzureEnvironmentResource must be present in the application…

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

Appendix: source

Thrown at src/Aspire.Hosting.Azure.Kubernetes/AzureKubernetesEnvironmentResource.cs:106

            return Task.FromResult<IEnumerable<PipelineStep>>([prepareStep, getCredentialsStep, getDestroyCredentialsStep]);
        }));

        Annotations.Add(new PipelineConfigurationAnnotation(async context =>
        {
            var k8sEnv = KubernetesEnvironment;
            var getDestroyCredentialsStep = context.GetSteps(this)
                .Single(step => step.Name == $"aks-get-credentials-for-destroy-{Name}");
            var kubernetesDestroySteps = context
                .GetSteps(HelmDeploymentEngine.GetKubernetesDestroyTag(k8sEnv.Name))
                .ToList();

            var deploymentStateManager = context.Services.GetRequiredService<IDeploymentStateManager>();
            var deploymentStateSection = await deploymentStateManager
                .AcquireSectionAsync($"Azure:Deployments:{Name}")
                .ConfigureAwait(false);

            var azureEnvironment = context.Model.Resources.OfType<AzureEnvironmentResource>().SingleOrDefault()
                ?? throw new InvalidOperationException(
                    $"Azure environment resource required by AKS environment '{Name}' was not found.");
            var destroyAzureStep = context.GetSteps(azureEnvironment)
                .SingleOrDefault(step => step.Name == $"destroy-azure-{azureEnvironment.Name}")
                ?? throw new InvalidOperationException(
                    $"Azure destroy step for environment '{azureEnvironment.Name}' was not found.");

            // A never-deployed AKS environment has no isolated kubeconfig to acquire. Likewise, a
            // partially deployed environment can persist the cluster ID before any Helm release saves
            // destroy state. In either case, aggregate Azure cleanup must skip cluster-scoped destroy
            // steps rather than block on reacquiring credentials when there is nothing known to clean
            // up. Explicitly targeting one of those Kubernetes cleanup steps still runs through the
            // credential prerequisite and fails rather than allowing the command to fall back to the
            // caller's ambient Kubernetes context.
            var targetStep = context.Services.GetRequiredService<IOptions<PipelineOptions>>().Value.Step;
            var hasPersistedAksIdentity = HasPersistedAksIdentity(deploymentStateSection.Data);
            var hasPersistedKubernetesCleanupState = hasPersistedAksIdentity &&
                await HasPersistedKubernetesCleanupStateAsync(
                    deploymentStateManager,

View on GitHub (pinned to 25830f84bd)