🚨 Azure Error: 'InvalidApiVersionParameter' — Cause, Fix, and Troubleshooting Guide

What this error means

Azure Resource Manager returns InvalidApiVersionParameter when the api-version supplied on a request is not a valid version for that resource type. Every ARM resource type publishes a set of dated API versions; a value that is malformed, retired, or simply never existed for the type is rejected outright. The literal error:

{
  "error": {
    "code": "InvalidApiVersionParameter",
    "message": "The api-version '2026-01-01' is invalid. The supported versions are '2024-11-04,2024-07-01,2024-01-01,2023-11-01,2023-05-01,2022-09-01'."
  }
}

Like other ARM version errors, the message lists exactly which versions are supported — so the fix is to pick one from that list.

How it shows up

• A REST call, az resource ... --api-version, or an ARM/Bicep deployment fails with InvalidApiVersionParameter.
• The message enumerates the supported versions, none of which match what you sent.
• A hand-written REST script uses a made-up or future date as the version.
• A template compiled against a newer Bicep/tooling emits an apiVersion the target cloud (e.g., a sovereign/Azure Government region) does not yet have.

Version and compatibility causes

• Non-existent or future version — a typo, an invented date, or a version that has not been released for the type.
• Wrong type/namespace — the api-version is valid for a different resource type than the one in the URL/template.
• Retired version — a very old API version that has been removed for that provider.
• Sovereign/region cloud lag — Azure Government, China, or a specific region does not carry the same version set as public global Azure.
• Manual REST calls — direct az rest or SDK-less HTTP requests where the caller hard-codes the version.

Confirming the versions in play

Ask the provider which API versions the exact type supports:

az provider show --namespace Microsoft.Storage \
  --query "resourceTypes[?resourceType=='storageAccounts'].apiVersions | [0]" -o json

That array is the authoritative allowed list. Confirm you are querying the right type — a namespace/type mismatch yields a different (or empty) list:

az provider show --namespace Microsoft.Storage \
  --query "resourceTypes[].resourceType" -o table

For a REST call, echo the version you are actually sending so you can compare it byte-for-byte:

az rest --method get \
  --url "https://management.azure.com/subscriptions/<sub>/providers/Microsoft.Storage/storageAccounts?api-version=2024-01-01" \
  --query "value[].name" -o table

Resolution

Use a supported version from the diagnose step. For a direct call:

az resource show \
  --ids /subscriptions/<sub>/resourceGroups/data-rg/providers/Microsoft.Storage/storageAccounts/mydata \
  --api-version 2024-01-01

In Bicep/ARM, set the type’s apiVersion to a real published version (Bicep validates this at compile time, which is the easiest guard):

resource sa 'Microsoft.Storage/storageAccounts@2024-01-01' = {
  name: 'mydata${uniqueString(resourceGroup().id)}'
  location: resourceGroup().location
  sku: { name: 'Standard_LRS' }
  kind: 'StorageV2'
}

For sovereign clouds, pull the supported versions from that cloud’s ARM endpoint (log in to the correct cloud first) rather than assuming public-cloud versions:

az cloud set --name AzureUSGovernment
az provider show --namespace Microsoft.Storage \
  --query "resourceTypes[?resourceType=='storageAccounts'].apiVersions | [0]" -o json

Keep tooling current so generated apiVersion values track what the provider actually offers; upgrade Bicep/CLI rather than hand-editing versions.

Planning upgrades

• Bicep catches this at build time. Compiling with a recent Bicep CLI flags an invalid apiVersion before deployment — prefer it over raw ARM JSON for this reason.
• Preview vs GA. A -preview version can be valid while the same date without the suffix is not (and vice versa); copy the exact string from the supported list.
• Version per type, not per namespace. Two types in the same provider can have different supported version sets; always query the specific resourceType.
• Sovereign clouds lag. Do not reuse a public-cloud template’s newest versions in Azure Government/China without checking that cloud’s provider.

Related upgrade errors

• NoRegisteredProviderFound — the region-plus-version sibling error, with the same “supported versions/locations” message.
• InvalidTemplateDeployment — pre-flight validation that surfaces version problems in a template.
• ResourceNotFound — a resolved-but-missing resource, often confused with a bad api-version on manual REST calls.