How can I enable custom Azure Policy definition versioning?

Chen Cheng 0 Reputation points
2026-08-13T14:33:34.37+00:00

I'm trying to use Azure Policy's custom definition versioning API. I'm specifically looking for the way to enable this API, not a versioning workaround.

Creating the root custom definition succeeds:

az policy definition create --name <name> --rules policy-rules.json --version 1.0.0

Creating a child version fails:

az policy definition version create --name <name> --version 1.1.0 --rules policy-rules.json

Error:

InvalidPolicyDefinitionVersionRequest: Creating policy definition versions is currently disabled in this environment. Please contact support for any questions.

What I have already checked:

  • The caller is Owner, and the request reaches Microsoft.Authorization/policyDefinitions/versions/write.
  • The result is the same at subscription and management-group scope.
  • Calling the REST endpoint directly produces the same error.
  • I tested API versions from 2023-04-01 through 2026-01-01-preview.
  • Updating the root definition's version also fails with: "Changing the value of the 'version' property is not yet supported in this environment."
  • No related registration appears in az feature list.

The stable REST documentation says PolicyDefinitionVersion supports policyType: Custom, and Azure CLI exposes az policy definition version create as a GA command. The CLI live-test recording also shows custom versions being created successfully in a Microsoft test environment.

How can this capability be enabled in a customer AzureCloud subscription? Is it currently allowlisted or private preview? If so, what is the exact enrollment or feature-registration path?

References:

REST API: https://learn.microsoft.com/en-us/rest/api/policy/policy-definition-versions/create-or-update?view=rest-policy-2025-11-01

Azure CLI issue with full reproduction details: https://github.com/Azure/azure-cli/issues/33890

Azure Policy
Azure Policy

An Azure service that is used to implement corporate governance and standards at scale for Azure resources.

0 comments

1 answer

Sort by: Most helpful
Most helpful Newest Oldest
  1. Ravi Varma Mudduluru 12,545 Reputation points Microsoft External Staff Moderator
    2026-08-19T04:05:16.34+00:00

    Hello @Chen Cheng

    Thank you for reaching out to Microsoft Q&A.

    The error you’re seeing (InvalidPolicyDefinitionVersionRequest: Creating policy definition versions is currently disabled in this environment) is expected with the current platform behavior.

    Azure Policy versioning (the ability to create and manage multiple versions under the same definition ID via the /versions path) is currently supported only for built-in policy definitions and initiatives. Support for custom definitions is planned but has not been enabled yet in customer Azure cloud environments.

    This is called out explicitly in the Azure Landing Zones documentation:

    “As of March 2025, Azure Policy version only supports built-in policies and initiatives. Custom policies and initiatives are not supported but are planned.” https://azure.github.io/Azure-Landing-Zones/policy/policyversioning/

    The official definition-structure docs also describe the multi-version capability in the context of built-ins only: https://learn.microsoft.com/en-us/azure/governance/policy/concepts/definition-structure-basics#version-preview

    There is no public feature flag or self-service registration that unlocks custom versioning at the moment (which matches what you already checked with az feature list).

    You can do:

    • Continue managing custom policy versions yourself via the metadata.version property and source control (Git + CI/CD). This remains the recommended approach for custom definitions.
    • When you need a breaking change, either update the existing definition in place or create a new definition with a different name.

    If the answer is helpful, please click "upvote" it. If you have extra questions about this answer, please click "Comment".

    Was this answer helpful?

    0 comments

Your answer

Answers can be marked as 'Accepted' by the question author and 'Recommended' by moderators, which helps users know the answer solved the author's problem.