Fix Azure CLI Errors: Setup, Auth & Update Guide
Why Azure CLI Errors Are Happening to You
I've seen this exact situation play out hundreds of times. You open a terminal, type an az command you've used confidently for months, and suddenly , nothing works. Maybe you get a cryptic az: command not found on Linux. Maybe Windows throws a 'az' is not recognized as an internal or external command error. Or maybe the command runs but returns something completely unexpected , a deprecated argument warning, a suddenly broken flag, or an authentication loop that just won't quit.
Azure CLI errors come from a handful of root causes, and Microsoft's own error messages rarely explain which one you're actually hitting. Here's what's really going on under the hood.
Version mismatches. Azure CLI moves fast. Version 2.80.0 dropped in November 2025, version 2.81.0 in December 2025, and the changes aren't always backwards-compatible. If you're running an older version and following documentation written for a newer release, the arguments simply don't exist yet on your machine. The CLI won't tell you "this argument was added in 2.81.0", it'll just throw an unrecognized argument error and leave you guessing.
Breaking changes after an update. This is the sneaky one. You do the right thing, you run az upgrade, and then your existing scripts break. Several commands in recent versions carried explicit breaking changes, the AKS team removed --no-ssh-key as an opt-in flag and made it the default behavior in 2.80.0. The Batch commands dropped --target-communication and --resource-tags entirely. If you had those flags hardcoded in a pipeline or script, they now silently (or noisily) fail.
Authentication token expiration and tenant confusion. Azure CLI caches login tokens locally. When those tokens expire, or when you're working across multiple Azure tenants and subscriptions, the CLI can silently pick the wrong context and fail with AADSTS70011, AADSTS50076, or the infuriating generic "Please run 'az login' to setup account" even when you're already logged in.
Extension and Bicep install failures. There's a documented bug in versions prior to 2.81.0 where running az bicep install --version x.y.z would silently skip the installation unless you explicitly set bicep.use_binary_from_path to false in your config. If you've ever pulled your hair out because Bicep "installed" but didn't actually update, that's exactly what happened.
Who sees these issues most? DevOps engineers who update their local CLI but forget to update CI/CD pipeline agents. Developers switching between personal subscriptions and enterprise tenants. Platform engineers who scripted against Azure CLI flags that quietly got deprecated. If any of that sounds like you, you're in the right place.
Browse all Microsoft fix guides →The Quick Fix, Try This First
Before you go deep into logs and config files, try this. It resolves about 70% of Azure CLI errors in under three minutes.
Open a terminal with administrator privileges (on Windows, right-click PowerShell or Command Prompt and select "Run as administrator"). Then run these three commands in sequence:
az upgrade
az account clear
az loginaz upgrade updates both the Azure CLI core and all installed extensions to their latest versions. This alone fixes broken commands caused by version gaps, and it patches known bugs like the Bicep install skip issue. Give it a minute, it pulls from Microsoft's CDN and verifies signatures.
After the upgrade completes, az account clear wipes out any cached credentials and stale tokens from your local credential store. This is the step most guides skip. Stale tokens cause authentication errors that look like permission problems but are really just expired session data.
Finally, az login opens a browser window for a fresh interactive sign-in. Pick the correct account, and once you're back in the terminal, run:
az account list --output tableThis shows every subscription tied to your account. If you're in an enterprise environment with multiple tenants, you might need to add the tenant ID explicitly:
az login --tenant YOUR_TENANT_IDIf after this your original command still fails, the issue is specific to the command itself, a breaking change, a deprecated argument, or a permission gap. Keep reading for the full step-by-step fix.
az version before and after the upgrade. Note both version numbers. If the post-upgrade version matches what's listed in the official release notes for your platform, and your command still fails, the problem is 100% command-specific, not the CLI installation itself. This saves 20 minutes of reinstall attempts.
Start here. You can't fix what you can't measure. Run this in your terminal:
az versionThis outputs a JSON block showing your exact CLI version and the version of every installed extension. The core Azure CLI version should be 2.81.0 or higher if you want access to all the fixes and features documented in the latest releases. Older versions are missing things like the --user-delegation-oid flag for storage SAS generation, the --pss-level parameter for AKS safeguards, and the Bicep installation bug fix.
Now check where the CLI binary actually lives:
# On Windows (PowerShell)
where.exe az
# On Linux/macOS
which azIf you see multiple paths, or if the path points somewhere unexpected like a Python virtual environment or a stale Homebrew install, you likely have conflicting Azure CLI installations. The wrong one is winning the PATH race and getting executed every time you type az.
On Windows, the official installer puts the binary at C:\Program Files (x86)\Microsoft SDKs\Azure\CLI2\wbin\az.cmd. On Ubuntu/Debian systems installed via Microsoft's official repo, it lives at /usr/bin/az. If your which az points somewhere else, your PATH is the problem.
To fix a Windows PATH issue: open System Properties → Advanced → Environment Variables. Under "System variables," find Path and click Edit. Make sure the Microsoft SDK path appears before any Python Scripts entries. Click OK, close and reopen your terminal.
If the version check passes and the path is correct, move to step 2. If the CLI won't even run at all, you likely need a clean reinstall, download the latest MSI installer from Microsoft's official Azure CLI documentation page and run it with administrator rights.
Authentication errors are the most common Azure CLI fix request I deal with. The good news: 90% of them come down to a stale token cache or a wrong subscription context. Here's how to clear it properly.
First, sign out completely:
az logoutThen clear the entire credential cache:
az account clearNow sign in fresh. For personal accounts:
az loginFor enterprise accounts with conditional access policies or MFA requirements, you may need device code flow if you're on a headless server:
az login --use-device-codeThis gives you a short code and a URL (https://microsoft.com/devicelogin). Open that URL in any browser, enter the code, complete MFA, and your terminal session authenticates automatically.
After login, confirm you're pointed at the right subscription:
az account show --output tableIf the wrong subscription is active, switch it:
az account set --subscription "YOUR_SUBSCRIPTION_NAME_OR_ID"For service principal authentication, common in CI/CD pipelines, make sure your environment variables are set correctly:
export AZURE_CLIENT_ID="your-app-id"
export AZURE_CLIENT_SECRET="your-secret"
export AZURE_TENANT_ID="your-tenant-id"
az login --service-principal \
--username $AZURE_CLIENT_ID \
--password $AZURE_CLIENT_SECRET \
--tenant $AZURE_TENANT_IDIf you see AADSTS70011, the OAuth scope is wrong, usually because the service principal doesn't have the right API permissions. If you see AADSTS50076, MFA is required and device code flow is your path forward.
A clean login with the correct subscription active should resolve the majority of "permission denied" and "resource not found" errors that are actually just auth context problems in disguise.
This one is painful because the upgrade itself is the right move, but it can break scripts that relied on arguments that no longer exist. Let me walk you through the most impactful breaking changes from recent versions and exactly how to update your code.
AKS: --no-ssh-key is now the default. In version 2.80.0, az aks create made --no-ssh-key the default behavior. If your script explicitly passed --no-ssh-key, remove it, it's no longer a valid flag. If your script relied on SSH keys being generated automatically without the flag, you now need to explicitly pass --generate-ssh-keys.
Batch pool: deprecated arguments removed. The --target-communication and --resource-tags arguments were removed from az batch pool create, az batch pool reset, and az batch pool set in version 2.80.0. If you see an error like unrecognized arguments: --target-communication, just remove that flag from your command. These features are now controlled through pool configuration JSON files rather than CLI flags.
PostgreSQL index-tuning redirect. If your automation scripts use az postgres flexible-server index-tuning, that command group is deprecated and will redirect you to az postgres flexible-server autonomous-tuning. Update your scripts to use the new command group to avoid deprecation warnings that may become errors in future versions.
The fastest way to audit your scripts for broken arguments is to run them with --debug appended. This surfaces the exact argument parsing step where the failure happens:
az aks create [your-flags] --debug 2>&1 | grep -i "error\|unrecognized"For pipeline YAML files in Azure DevOps, check the AzureCLI task version, if you're pinned to an old CLI version in your agent pool, the task won't pick up your local upgrade. Set the azureSubscription task to use the hosted agents and explicitly specify addSpnToEnvironment: true to ensure it uses current versions.
This bug is officially documented and was patched in version 2.81.0, but I still see it trip people up, especially on build agents that haven't been refreshed in a while. Here's exactly what was happening and how to confirm your environment is clean.
Before 2.81.0, running this command:
az bicep install --version v0.30.3...would silently skip the installation and keep whatever Bicep version was already present. No error. No warning. Just quiet failure. The only way it worked was if you had explicitly set bicep.use_binary_from_path to false in the Azure CLI config. Obviously, nobody knew they had to do that.
First, confirm your CLI is on 2.81.0 or newer (the fix release). If not, run az upgrade. Then clear any potentially broken Bicep install:
az bicep uninstall
az bicep install --version v0.30.3Verify it took effect:
az bicep versionIf you need to manage Bicep installs on systems where the binary is already in the PATH, you can explicitly control behavior via:
az config set bicep.use_binary_from_path=falseThis tells the CLI to always manage Bicep through its own installer rather than deferring to whatever bicep binary is in the system PATH. On shared build agents where multiple teams may have installed Bicep different ways, this is the configuration you want.
To check all current Azure CLI config values at once:
az config listOn Windows, the CLI config file lives at %USERPROFILE%\.azure\config. On Linux/macOS it's at ~/.azure/config. You can edit it directly with any text editor if the az config set command itself is misbehaving. The file format is simple INI-style, just add or modify the [bicep] section:
[bicep]
use_binary_from_path = falseSave the file, open a new terminal, and your Bicep version installs should work exactly as expected going forward.
Two areas that generate a lot of Azure CLI fix tickets right now: PostgreSQL Flexible Server commands and Storage SAS generation. Both had significant updates in recent releases that catch people off guard.
PostgreSQL Flexible Server, High Availability and Fabric Mirroring. Starting with version 2.81.0, you can enable Fabric mirroring on high availability servers running PostgreSQL 17 or later. If you're trying to configure this and getting an error, confirm your server version first:
az postgres flexible-server show \
--resource-group myRG \
--name myServer \
--query "version"The server must be PostgreSQL 17+ and have high availability already enabled. Attempting to start Fabric mirroring on PostgreSQL 16 or below will fail. The same version check applies if you're attempting a major version upgrade to PostgreSQL 18, that path is now supported via:
az postgres flexible-server upgrade \
--resource-group myRG \
--name myServer \
--version 18For High Availability with PremiumV2_LRS storage type, which is now supported, make sure you're specifying the storage type explicitly in your create or update command, it won't infer it automatically.
Storage SAS Generation, new --user-delegation-oid flag. Version 2.81.0 added the --user-delegation-oid parameter to blob, container, filesystem, share, file, queue, and directory SAS generation commands. If you're generating user-delegation SAS tokens and they're not scoping correctly to the intended user identity, this is the flag you need:
az storage blob generate-sas \
--account-name myaccount \
--container-name mycontainer \
--name myblob \
--permissions r \
--expiry 2026-05-01 \
--user-delegation-oid "oid-of-target-user" \
--auth-mode login \
--output tsvIf you get an error saying unrecognized arguments: --user-delegation-oid, your CLI is older than 2.81.0. Run az upgrade and retry. Also note that az storage fs file generate-sas is a brand new command added in 2.81.0, it didn't exist before, so if you were working around that gap with workarounds, you can now drop those and use the dedicated command.
Advanced Troubleshooting for Azure CLI Errors
When the standard steps don't cut it, you need to go deeper. Here's how I approach stubborn Azure CLI problems in enterprise environments.
Enable debug output. Add --debug to any failing command. This dumps the full HTTP request/response cycle, the exact argument parsing, and the SDK calls being made. It's verbose, but it pinpoints whether a failure is auth, network, argument parsing, or a service-side error:
az aks create --resource-group myRG --name myCluster --debug 2>&1 | tee debug_output.txtPipe it to a file so you can actually read it. Look for AuthenticationError, CLIError, or HTTP status codes like 403 Forbidden or 400 Bad Request with the response body, the response body from Azure's REST API usually tells you exactly what's wrong.
Check extension conflicts. Azure CLI extensions are installed separately and can fall behind or conflict with the core CLI after an upgrade. List all installed extensions:
az extension list --output tableUpdate them all at once:
az extension update --allIf an extension is causing problems, remove and reinstall it:
az extension remove --name extension-name
az extension add --name extension-nameAKS namespace management issues. Version 2.80.0 introduced the az aks namespace command group for managed namespaces. If you're on an older version and calling these commands, they won't exist. After upgrading, the full namespace lifecycle looks like this:
az aks namespace add --resource-group myRG --cluster-name myCluster --name myNamespace
az aks namespace list --resource-group myRG --cluster-name myCluster
az aks namespace show --resource-group myRG --cluster-name myCluster --name myNamespaceDomain-joined and corporate proxy environments. If you're behind a corporate proxy and getting SSL errors or connection timeouts, set the HTTP proxy variables before running CLI commands:
export HTTPS_PROXY="http://proxy.corp.example.com:8080"
export HTTP_PROXY="http://proxy.corp.example.com:8080"
export NO_PROXY="localhost,127.0.0.1,.corp.example.com"On Windows, use set instead of export. Corporate environments with SSL inspection may also require you to add the proxy's root certificate to the Azure CLI's certificate store:
az config set core.cafile=/path/to/corp-root-ca.pemCognitive Services and AI Foundry command errors. Version 2.80.0 added az cognitiveservices account connection, az cognitiveservices account project, and az cognitiveservice agent as new command groups. If these commands aren't found, you need to upgrade, and note the singular cognitiveservice (no 's') for the agent command group specifically, which is intentional in the CLI naming.
SQL Managed Instance memory configuration. The az sql mi create/update commands now support a --memory-size-in-gb parameter. If you're getting argument errors on this parameter, verify your CLI version is current and that your SQL MI SKU supports memory configuration changes, not all service tiers expose this.
--debug output and your az version output before you contact Microsoft Support. Also note your Azure region and subscription ID, Azure control plane issues are often region-specific and Microsoft's support team will need those to pull backend logs.
Prevention & Best Practices for Azure CLI
I know it's tempting to skip this section now that your immediate Azure CLI error is fixed. Don't. The people who come back with the same problems six months later are the ones who skipped this part.
The number one thing you can do is pin your Azure CLI version explicitly in CI/CD pipelines rather than always pulling the latest. "Always latest" sounds like a good idea until a breaking change in a new release drops at 2 AM and your deployment pipeline starts failing. In Azure DevOps, you can pin the CLI version on your hosted agent tasks. In GitHub Actions, the azure/cli action accepts an azcliversion parameter. Use it.
At the same time, you absolutely need to stay current on your local development machine, the security patches alone make this non-negotiable. Set up a simple reminder to run az upgrade once a month. Two minutes of maintenance beats two hours of emergency debugging.
Keep your Azure CLI scripts version-aware. Add a version check at the top of any script that uses features from a specific version:
REQUIRED_VERSION="2.81.0"
CURRENT_VERSION=$(az version --query '"azure-cli"' -o tsv)
if [[ "$CURRENT_VERSION" < "$REQUIRED_VERSION" ]]; then
echo "Azure CLI $REQUIRED_VERSION or higher required. Run: az upgrade"
exit 1
fiFor teams managing multiple Azure environments, use named CLI profiles to avoid subscription context confusion. Set up separate config directories using the AZURE_CONFIG_DIR environment variable, one per environment (dev, staging, prod). This prevents the classic "I ran that command against prod when I thought I was in dev" disaster.
AZURE_CONFIG_DIR=~/.azure-prod az account show
AZURE_CONFIG_DIR=~/.azure-dev az account show- Run
az upgrademonthly on local machines; pin explicit versions in CI/CD pipelines - Use
az account showas the first line of any automation script to confirm the active subscription before taking any action - Store service principal credentials in Azure Key Vault or GitHub/Azure DevOps secret stores, never hardcode them in scripts or pipeline YAML files
- Subscribe to the official Azure CLI release notes via RSS or the GitHub releases page so breaking changes never blindside you
Frequently Asked Questions
Why does az upgrade say "nothing to upgrade" but my az version still shows an old version?
This usually means the Azure CLI installation that's actually being executed isn't the one the upgrade command updated. Run where az (Windows) or which az (Linux/macOS) to see exactly which binary is in your PATH. If the upgrade ran against one installation path but your terminal is resolving a different one, for example, a pip-installed copy in a virtual environment, you'll see this mismatch. Fix it by removing the secondary installation or adjusting your PATH order so the correct CLI binary wins.
I'm getting "Please run az login" even though I already logged in, what's wrong?
The most common cause is token expiration. Azure CLI access tokens expire after one hour, and if your terminal session has been running longer than that without activity, the cached token is dead. Run az account clear followed by az login to get a fresh token. If you're in a CI/CD pipeline, the issue is likely that the service principal secret has expired, check the app registration in Entra ID (formerly Azure Active Directory) and rotate the client secret, then update your pipeline secret store.
My AKS scripts broke after upgrading Azure CLI, why?
Version 2.80.0 introduced breaking changes to az aks create and az batch pool commands. The --no-ssh-key flag is now the default behavior for AKS cluster creation, so if your script passed that flag explicitly, remove it. If your script expected SSH keys to be auto-generated, add --generate-ssh-keys explicitly. For Batch pool commands, --target-communication and --resource-tags were removed entirely, strip those arguments from your commands and manage those settings via pool configuration files instead.
How do I fix "unrecognized arguments: --user-delegation-oid" in storage SAS commands?
The --user-delegation-oid parameter was added to storage SAS generation commands in Azure CLI version 2.81.0. If you're seeing this error, your CLI version is older than that release. Run az version to confirm, then run az upgrade to get to 2.81.0 or newer. After upgrading, close and reopen your terminal to make sure the new binary is loaded. The flag is supported across az storage blob, az storage container, az storage fs, az storage share, az storage file, and az storage queue SAS generation commands.
Can I use az postgres flexible-server upgrade to go to PostgreSQL 18?
Yes, major version upgrade to PostgreSQL 18 is now supported via the Azure CLI. Use az postgres flexible-server upgrade --resource-group myRG --name myServer --version 18. Before you run this, back up your databases and test the upgrade in a non-production environment first, major version upgrades are one-way operations that cannot be reversed through the CLI. Microsoft recommends reviewing the PostgreSQL 18 release notes for any deprecated features or behavior changes that might affect your applications before triggering the upgrade.
Why is my Bicep install command not actually installing the version I specified?
This is a known bug that was fixed in Azure CLI 2.81.0. In older versions, az bicep install --version x.y.z would silently skip the installation if a Bicep binary was already present, unless you had bicep.use_binary_from_path set to false in your CLI config. Upgrade to 2.81.0 or newer by running az upgrade, then run az bicep uninstall followed by az bicep install --version x.y.z again. Verify with az bicep version that the correct version is now active.