🚨 Azure Error Guide: 'MissingSubscriptionRegistration' — Register the Resource Provider

Overview

Azure Resource Manager raises this error the first time a subscription tries to create a resource in a service whose resource provider has never been registered on that subscription. It surfaces from the CLI, from az deployment / Bicep, and from Terraform:

Code: MissingSubscriptionRegistration
Message: The subscription is not registered to use namespace 'Microsoft.ContainerService'.
See https://aka.ms/rps-not-found for how to register subscriptions.

Every Azure service is fronted by a resource provider — Microsoft.ContainerService for AKS, Microsoft.Network for VNets, Microsoft.KeyVault for Key Vault, and so on. A provider must be in the Registered state on the subscription before ARM will accept a create/update for any resource type it owns. On brand-new subscriptions, on subscriptions where auto-registration was disabled by policy, or when you start using a service for the first time, the provider is still NotRegistered and the deployment is rejected immediately — before any resource is created.

Symptoms

• A deployment fails instantly with MissingSubscriptionRegistration and a specific Microsoft.* namespace named in the message.
• The failure is deterministic and happens at validation/submission time, not partway through.
• A previously working template fails on a new subscription while succeeding on an older one.
• Terraform apply returns the same error mid-plan when it reaches the first resource of an unregistered provider.
• Portal deployments of the same resource type succeed (the portal auto-registers providers), masking the problem in CI where auto-registration is off or the identity lacks permission.
• Only some resources in a large template fail — the ones belonging to a provider you have never used before (e.g. Microsoft.OperationalInsights, Microsoft.Cdn, Microsoft.DBforPostgreSQL).

Common Root Causes

• Brand-new subscription — no providers beyond the defaults have been registered yet.
• First use of a service — you are deploying, say, API Management or Front Door for the first time and its provider was never touched.
• Auto-registration disabled — an Azure Policy or org standard prevents implicit provider registration, so it must be done explicitly.
• Insufficient permissions — the deploying service principal lacks */register/action (part of Contributor and Owner), so ARM never auto-registered the provider.
• A dependent/hidden provider — a resource pulls in a companion provider you did not expect, e.g. diagnostic settings needing Microsoft.Insights, or a private endpoint needing Microsoft.Network.
• Wrong subscription context — the CLI/Terraform is pointed at a different subscription than the one where you registered the provider.

Diagnostic Workflow

First confirm which subscription you are actually operating on — most “I already registered it” cases are a context mismatch:

az account show --query "{name:name, id:id, tenant:tenantId}" -o table

List every provider and its registration state, then filter to the ones that are not registered:

az provider list --query "[?registrationState!='Registered'].{Namespace:namespace, State:registrationState}" -o table

Check the exact namespace from the error message:

az provider show --namespace Microsoft.ContainerService --query registrationState -o tsv

Confirm your identity can register providers (look for */register/action, Contributor, or Owner at subscription scope):

az role assignment list --assignee <appId-or-objectId> --scope /subscriptions/<subId> -o table

If the failing resource comes from a template, find which providers it needs so you can register them all at once instead of one round-trip per failure:

az deployment sub validate --location <region> --template-file main.bicep --parameters @params.json

Example Root Cause Analysis

A team’s Terraform pipeline deployed cleanly to the shared dev subscription for months. A new production subscription was provisioned, the same code was pointed at it, and terraform apply failed:

Error: creating Kubernetes Cluster: managedclusters.ManagedClustersClient#CreateOrUpdate:
Code="MissingSubscriptionRegistration"
Message="The subscription is not registered to use namespace 'Microsoft.ContainerService'."

The engineer’s first assumption was a broken Terraform provider version. But az provider show told the real story:

az provider show --namespace Microsoft.ContainerService --query registrationState -o tsv
# NotRegistered

The production subscription was days old and no one had ever created an AKS cluster in it via the portal, so Microsoft.ContainerService had never auto-registered. Compounding it, the pipeline’s service principal had a custom role scoped to specific resource groups that omitted */register/action, so ARM could not auto-register on its behalf. The fix was two steps: grant the SP subscription-scoped rights to register providers (or have an owner pre-register), then register the namespace:

az provider register --namespace Microsoft.ContainerService --wait

Registration is asynchronous; --wait blocks until the state flips to Registered. Re-running apply then succeeded. The durable fix was adding a provider-registration step to subscription bootstrap so new subscriptions never hit this.

Prevention Best Practices

• Bootstrap providers at subscription creation. Register the full set of namespaces your platform uses as part of landing-zone/subscription vending, so no first deployment ever races registration.
• Register in code. Keep a canonical list of required Microsoft.* providers and register them idempotently in your pipeline before apply (az provider register is safe to re-run).
• Grant register permission. Ensure deploying identities have */register/action (Contributor/Owner or a custom role that includes it) so ARM can auto-register.
• Don’t disable auto-registration blindly. If policy blocks implicit registration, pair it with an explicit registration step — otherwise every new service is a broken deployment.
• Register dependent providers too. Include the quiet companions — Microsoft.Insights, Microsoft.Network, Microsoft.OperationalInsights, Microsoft.ManagedIdentity — in your baseline list.
• Verify state, not intent. In CI, check registrationState == Registered (and wait for it) rather than assuming a fire-and-forget register call already completed.

Quick Command Reference

# Which subscription am I on?
az account show -o table

# List providers that are not registered
az provider list --query "[?registrationState!='Registered'].namespace" -o tsv

# Check one namespace
az provider show --namespace Microsoft.ContainerService --query registrationState -o tsv

# Register and wait for it to complete
az provider register --namespace Microsoft.ContainerService --wait

# Register a whole baseline set idempotently
for ns in Microsoft.ContainerService Microsoft.Network Microsoft.KeyVault \
          Microsoft.Insights Microsoft.OperationalInsights Microsoft.ManagedIdentity; do
  az provider register --namespace "$ns"
done

# Confirm your identity can register providers
az role assignment list --assignee <appId> --scope /subscriptions/<subId> -o table

Conclusion

MissingSubscriptionRegistration is not a bug in your template — it is Azure telling you the subscription has never been enabled for the service you are deploying. The fix is quick (az provider register --namespace <ns> --wait), but the real cure is making provider registration a deterministic part of subscription bootstrap and pipeline setup, and ensuring deploying identities have the rights to register. Do that once and this error stops appearing every time a new subscription or a new service enters the picture.