microsoft/aspire · critical · InvalidOperationException

An Azure principal parameter was not supplied a value…

Error message

An Azure principal parameter was not supplied a value. Ensure you are using an environment that supports role assignments, for example AddAzureContainerAppEnvironment.

What it means

During Bicep deployment parameter binding, a principal-related parameter (e.g. PrincipalId) was left null. In publish mode Aspire refuses to continue because role-assignment parameters require an environment that populates them (such as one created with AddAzureContainerAppEnvironment); azd normally fills these with a managed identity.

Solutions

Use an environment that supports role assignments, e.g. builder.AddAzureContainerAppEnvironment(...).
Explicitly supply the principal parameters on the resource (Params[KnownParameters.PrincipalId] = ...) before publishing.
If you intend azd-style deployment, run through the flow that populates principal parameters instead of direct publish.
Verify with context that the resource's Parameters dictionary has non-null PrincipalId/PrincipalType before publishing.

Example fix

// before
builder.AddAzureEnvironment(); // no role-assignment support
// after
builder.AddAzureContainerAppEnvironment("env");

Defensive patterns

Strategy: validation

Validate before calling

if (resource.Parameters.TryGetValue(AzureBicepResource.KnownParameters.PrincipalId, out var pid) && pid is null)
{
    throw new InvalidOperationException("PrincipalId is unset; publish requires an environment supporting role assignments (AddAzureContainerAppEnvironment).");
}

Try / catch

try { await provisioner.ProvisionAsync(...); } catch (InvalidOperationException ex) when (ex.Message.Contains("principal parameter")) { logger.LogError(ex, "Publish environment does not support role assignments"); throw; }

Prevention

Always create publish environments with AddAzureContainerAppEnvironment.
Never leave KnownParameters.PrincipalId null when publishing.
Test `aspire publish` in CI to catch missing principal configuration early.

When it happens

Trigger: Running `aspire publish`/deploy where a Bicep resource declares AzureBicepResource.KnownParameters.PrincipalId (or ValidateUnknownPrincipalParameter path) but no value was bound, and context.ExecutionContext.IsPublishMode is true.

Common situations: Using a plain publish environment that doesn't support role assignments; forgetting to configure AddAzureContainerAppEnvironment; migration from azd flows where azd silently supplied principal parameters; calling aspire deploy without a deployment-capable environment.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Azure/Provisioning/Provisioners/BicepProvisioner.cs:1387

        };
    }

    private static void PopulateWellKnownParameters(AzureBicepResource resource, ProvisioningContext context)
    {
        static void ValidateUnknownPrincipalParameter(ProvisioningContext context)
        {
            // Application principal parameters can only be populated in run mode. Published artifacts
            // bind them from their outer template because the application identity can differ from the
            // credential applying the deployment.

            // We assume that the BicepProvisioner only runs in publish mode during `aspire deploy` operations
            // and not from azd. azd fills in principal parameters during its deployment process with a managed
            // identity it creates. The deployment-principal parameters are the exception: direct `aspire deploy`
            // intentionally binds them from the current credential because that identity performs subsequent
            // data-plane operations.
            if (context.ExecutionContext.IsPublishMode)
            {
                throw new InvalidOperationException("An Azure principal parameter was not supplied a value. Ensure you are using an environment that supports role assignments, for example AddAzureContainerAppEnvironment.");
            }
        }

        if (resource.Parameters.TryGetValue(AzureBicepResource.KnownParameters.PrincipalId, out var principalId) && principalId is null)
        {
            ValidateUnknownPrincipalParameter(context);

            resource.Parameters[AzureBicepResource.KnownParameters.PrincipalId] = context.Principal.Id;
        }

        var hasUserPrincipalId = resource.Parameters.TryGetValue(AzureBicepResource.KnownParameters.UserPrincipalId, out var userPrincipalId);
        var populatedUserPrincipalId = false;
        if (hasUserPrincipalId && userPrincipalId is null)
        {
            // Published artifacts bind this deployment-principal parameter from the outer
            // main.bicep template. Direct `aspire deploy` has no outer template, so use the
            // authenticated principal that performs the data-plane deployment.
            resource.Parameters[AzureBicepResource.KnownParameters.UserPrincipalId] = context.Principal.Id;

View on GitHub (pinned to 25830f84bd)