microsoft/aspire · error · InvalidOperationException

Azure Key Vault resources cannot change location because…

Error message

Azure Key Vault resources cannot change location because soft-deleted vault names remain reserved globally. Use delete, reprovision, or forget state to recover this resource.

What it means

Key Vault resources are blocked from location changes because soft-deleted vault names stay reserved globally; moving to a new location with the same name would conflict with the tombstone. The controller throws preemptively with recovery guidance.

Solutions

Use the delete flow, then reprovision in the new location
Use 'forget state' to reset the vault's deployment state and reprovision elsewhere
Purge or wait out the soft-delete period, then change location

Example fix

// before
aspire change-location --resource vault1 --location eastus // blocked
// after
aspire delete --resource vault1
aspire reprovision --resource vault1 --location eastus

Defensive patterns

Strategy: validation

Validate before calling

if (targetResources.Any(r => r.AzureResource is IAzureKeyVaultResource)) { /* route to delete/reprovision flow instead of location change */ }

Type guard

bool IsKeyVault(IAzureResource r) => r is IAzureKeyVaultResource;

Try / catch

try { await ChangeLocationAsync(...); } catch (InvalidOperationException ex) when (ex.Message.Contains("Key Vault")) { /* use delete + reprovision or forget-state */ }

Prevention

Never attempt location changes on Key Vault resources; recreate instead
Understand soft-delete reservation rules before renaming or moving vaults

When it happens

Trigger: Changing the location on a target containing an IAzureKeyVaultResource; attempting environment-wide location change when a Key Vault is in scope.

Common situations: Migrating an app to a new Azure region that includes Key Vault; re-running location change after a vault was soft-deleted in another region.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Azure/AzureProvisioningController.cs:1343

        {
            yield return parentRelationship.Resource;
        }
    }

    private static bool IsKeyVaultTarget(DistributedApplicationModel model, string resourceName)
    {
        return GetTargetAzureResources(model, resourceName, includeAnnotationParentRelationships: false)
            .Any(static resource => resource.AzureResource is IAzureKeyVaultResource);
    }

    private static void ThrowIfKeyVaultLocationChangeTarget(DistributedApplicationModel model, string resourceName)
        => ThrowIfKeyVaultLocationChangeTarget(GetTargetAzureResources(model, resourceName, includeAnnotationParentRelationships: false));

    private static void ThrowIfKeyVaultLocationChangeTarget(IReadOnlyList<(IResource Resource, IAzureResource AzureResource)> targetResources)
    {
        if (targetResources.Any(static resource => resource.AzureResource is IAzureKeyVaultResource))
        {
            throw new InvalidOperationException(AzureProvisioningStrings.ChangeResourceLocationKeyVaultUnsupported);
        }
    }

    private static void ThrowIfKeyVaultEnvironmentLocationChange(DistributedApplicationModel model, string? currentLocation, string? requestedLocation)
    {
        if (string.IsNullOrWhiteSpace(currentLocation) ||
            string.IsNullOrWhiteSpace(requestedLocation) ||
            string.Equals(currentLocation, requestedLocation, StringComparisons.AzureLocation))
        {
            return;
        }

        ThrowIfKeyVaultLocationChangeTarget(GetProvisionableAzureResources(model));
    }

    private static bool TryGetAzureResource(
        IReadOnlyList<(IResource Resource, IAzureResource AzureResource)> azureResources,
        IResource target,

View on GitHub (pinned to 25830f84bd)