Fix Azure Machine Learning API v2 Setup & Config Errors

The Azure Machine Learning CLI v2 is not part of the base Azure CLI install. It's a separate extension, and the extension name matters. The old v1 extension was called azure-cli-ml. The current v2 extension is simply called ml. Running az ml --help on a machine that still has the v1 extension will show you v1 commands, and those commands will fail against a v2 workspace configuration.

Here's the clean install sequence for the v2 extension:

# Check what you currently have
az extension list --output table

# Remove v1 extension if it shows up
az extension remove --name azure-cli-ml

# Install the current v2 extension
az extension add --name ml --upgrade

# Confirm the version installed
az ml --version

As of mid-2026, you want to see a version number in the 2.x.x range. If you see 1.x.x, the old extension is still active somewhere in your extension path.

On corporate machines, IT policy sometimes blocks extension installs from the default PyPI-backed feed. If az extension add fails with a permissions error or a network timeout, try installing offline using a wheel file downloaded separately and pointing the CLI at it with --source <path-to-whl>. Alternatively, Azure Cloud Shell comes with the ml extension pre-installed and is a solid fallback for teams where local installs are locked down.

When the install succeeds, run az ml job list --help. You should see a clean help page with options like --workspace-name and --resource-group. That confirms the extension is wired up correctly.

Authentication is the second most common failure point, and it shows up differently depending on whether you're using the CLI or the Python SDK v2. The error message is rarely helpful, you'll often see something like AuthenticationError, WorkspaceNotFound, or a generic 403 that doesn't tell you whether it's your credentials, your subscription, or your workspace name that's wrong.

For CLI v2, the cleanest path is interactive login followed by explicit scope setting:

# Interactive login
az login

# List your subscriptions to confirm which one you're on
az account list --output table

# Set the right subscription if you have multiple
az account set --subscription "<subscription-id-or-name>"

# Set workspace defaults so you don't have to pass them every command
az configure --defaults group=myResourceGroup workspace=myMLWorkspace

For Python SDK v2, workspace authentication uses DefaultAzureCredential from the azure-identity package, which tries a chain of credential sources. In a local dev environment, it falls back to interactive browser login. In a CI/CD pipeline, it should pick up a service principal via environment variables. Here's the standard connection pattern:

from azure.ai.ml import MLClient
from azure.identity import DefaultAzureCredential

ml_client = MLClient(
    credential=DefaultAzureCredential(),
    subscription_id="<your-subscription-id>",
    resource_group_name="<your-resource-group>",
    workspace_name="<your-workspace-name>"
)

# Test the connection
print(ml_client.workspaces.get(ml_client.workspace_name))

If DefaultAzureCredential fails in a pipeline context, check that the environment variables AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_CLIENT_SECRET are all set and that the service principal has at least Contributor access on the ML workspace resource. Role assignment errors show up as 403s and are managed through Azure IAM, not the ML workspace itself.

This is where most data scientists lose an hour. The Azure Machine Learning CLI v2 uses YAML files to define assets and workflows, jobs, environments, components, pipelines, models, endpoints. The YAML file is not just configuration metadata; it's the primary way you tell Azure Machine Learning what your job is, what compute it should run on, what environment it needs, and where your scripts live.

A minimal working job YAML looks like this:

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
type: command
display_name: my-first-job
experiment_name: my-experiment
code: ./src
command: python train.py --data ${{inputs.training_data}}
inputs:
  training_data:
    type: uri_folder
    path: azureml:my-dataset@latest
environment: azureml:AzureML-sklearn-1.0-ubuntu20.04-py38-cpu@latest
compute: azureml:my-compute-cluster

The most common YAML errors I see are:

• Wrong $schema URL, if the schema URL is outdated or mistyped, validation fails silently or with a confusing error
• Missing azureml: prefix on compute or environment references, without it, Azure treats the value as a literal string, not a workspace asset reference
• Indentation errors, YAML is whitespace-sensitive; mixing tabs and spaces is the fastest way to get a parse error that points to the wrong line
• Referencing a compute or dataset that doesn't exist yet, the YAML validates references against your actual workspace

Validate before submitting with:

az ml job create --file my_job_definition.yaml --dry-run

The --dry-run flag runs validation without actually submitting. If the dry run passes, the actual job submission will almost always succeed.

Compute errors are one of the most disruptive Azure Machine Learning API v2 problems because they often don't surface until after job submission, your job sits in a "queued" state for minutes before finally failing with a vague compute-related message.

The two most common compute errors are ComputeNotFound and QuotaExceeded. Here's how to address each.

For ComputeNotFound, confirm the compute target actually exists in your workspace:

az ml compute list --output table

If your compute cluster isn't in that list, you need to create it. The CLI v2 way to provision a basic CPU cluster:

az ml compute create --name my-compute-cluster \
  --type AmlCompute \
  --min-instances 0 \
  --max-instances 4 \
  --size Standard_DS3_v2

Set --min-instances 0 so the cluster scales to zero when idle, this prevents unnecessary charges when you're not running jobs.

For QuotaExceeded, the fix is either to request a quota increase through the Azure portal at Subscriptions → Usage + Quotas, or to switch your YAML to target a VM size that you have quota for. Run az ml compute show --name <cluster-name> to see what size is provisioned. You can also target serverless compute, which uses Azure-managed infrastructure and avoids the need to manage cluster provisioning yourself, an option worth knowing about when you're in development and don't want to babysit compute resources.

When the right compute is available and quota is sufficient, jobs should move from "queued" to "running" within a few minutes for an already-warm cluster, or within about 5-10 minutes if the cluster needs to scale up from zero.

Getting your model trained is half the battle. The other half is deploying it so something can actually call it. Azure Machine Learning v2 uses managed online endpoints for real-time inference and batch endpoints for batch inference. Both are configured and deployed through the CLI v2 or SDK v2, and both have their own failure modes.

A common real-time endpoint deployment YAML:

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: my-endpoint
auth_mode: key

And the deployment YAML that attaches a model to it:

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: blue
endpoint_name: my-endpoint
model: azureml:my-model@latest
environment: azureml:AzureML-sklearn-1.0-ubuntu20.04-py38-cpu@latest
code_configuration:
  code: ./score
  scoring_script: score.py
instance_type: Standard_DS3_v2
instance_count: 1

Deploy with:

az ml online-endpoint create --file endpoint.yaml
az ml online-deployment create --file deployment.yaml --all-traffic

The most frequent deployment failures are a scoring_script that throws an unhandled exception at startup, or an environment that's missing a package the scoring script imports. To debug, pull the deployment logs immediately after a failed deployment:

az ml online-deployment get-logs \
  --name blue \
  --endpoint-name my-endpoint \
  --lines 100

Look for Python tracebacks in those logs, they'll tell you exactly what failed in your scoring script. A missing init() function or a run() function with the wrong signature are the two most common culprits. Once you see the traceback, fix the script, update the environment if a package is missing, and redeploy.