Azure Container Instances: Fix Common Errors & Setup Issues

The Azure Portal gives you a high-level status, but it hides the details you actually need. Go straight to the CLI or REST API for real diagnostic output.

In the Portal, navigate to your container group: Portal → Resource Groups → [your group] → Container Instances → [your container name] → Containers. Click the container name, then select the Events tab. You'll see a timestamped list of provisioning events. If the container never started, this is where the image pull error or network provisioning failure will appear.

For a richer view, use the CLI:

az container show \
  --resource-group YOUR_RG \
  --name YOUR_CONTAINER \
  --output table

The provisioningState field will read Succeeded, Failed, or Creating. If it's stuck on Creating for more than 3–4 minutes, something is blocking the provisioning pipeline, usually a network issue or an invalid resource spec.

Note the osType field too. ACI supports both Windows and Linux containers, but several features, including volume mounting (Azure Files, emptyDir, GitRepo, secret), GPU resources, and multiple containers per group, are currently restricted to Linux containers only. If you're on Windows and expecting multi-container support or Azure Files mounts, that's your problem right there.

If the state is Failed, look at containers[0].instanceView.currentState.detailStatus. A value of CrashLoopBackOff means the app is starting and crashing repeatedly. OOMKilled means the container hit its memory limit. Error with no exit code usually signals an image pull failure or a network-level provisioning problem.

Once you've identified the failure category, you know which step below applies to your situation.

Private registry authentication is one of the most common sources of Azure Container Instances deployment failures. If your container image lives in an Azure Container Registry (ACR) instance, there are two ways to authenticate: explicit credentials (username and password) or managed identity. Managed identity is the right long-term approach, it means you don't embed credentials anywhere in your container group definition.

To set up managed identity for ACR image pulls, first enable a system-assigned managed identity on your container group. Then assign the AcrPull role to that identity scoped to your ACR instance:

# Assign AcrPull role to the managed identity
az role assignment create \
  --assignee YOUR_MANAGED_IDENTITY_PRINCIPAL_ID \
  --role AcrPull \
  --scope /subscriptions/YOUR_SUB_ID/resourceGroups/YOUR_RG/providers/Microsoft.ContainerRegistry/registries/YOUR_ACR_NAME

Then deploy the container group with the identity and registry reference:

az container create \
  --resource-group YOUR_RG \
  --name mycontainer \
  --image YOUR_ACR.azurecr.io/myapp:latest \
  --acr-identity YOUR_MANAGED_IDENTITY_RESOURCE_ID \
  --assign-identity YOUR_MANAGED_IDENTITY_RESOURCE_ID

If you're using explicit credentials and getting a 401 Unauthorized error, double-check that admin access is enabled on the ACR instance: Portal → Container Registry → [your registry] → Settings → Access keys → Admin user: Enabled. Copy the username and one of the two passwords, then pass them via --registry-username and --registry-password in your deploy command.

Also confirm the registry is in a supported configuration. ACI supports Docker Hub, Azure Container Registry, and other cloud-based Docker-compatible registries. If you're pulling from a self-hosted registry over a private endpoint only, you'll need a VNet-deployed container group with proper DNS resolution to reach it.

A successful image pull will show an event like Pulling image "YOUR_IMAGE" followed by Successfully pulled image in the container events. If you see those two events, your image pull is working, and the problem is in the application startup, not authentication.

This one trips up a lot of engineers when they first move from standalone ACI deployments to VNet-integrated ones. The rule is non-negotiable: if you deploy your container group into a virtual network, you must use a NAT gateway for outbound connectivity. That is the only supported configuration.

Without a NAT gateway, your VNet-deployed container group will have no outbound internet connectivity, it can receive traffic if you've set it up correctly, but it cannot initiate outbound connections. Applications that phone home to an API, pull a config from a URL, or connect to an external database will silently fail or time out, and the container logs will show connection refused or timeout errors rather than anything pointing to the actual network configuration problem.

Here's how to attach a NAT gateway to the subnet your container group uses:

# Create a public IP for the NAT gateway
az network public-ip create \
  --resource-group YOUR_RG \
  --name myNatGatewayIP \
  --sku Standard \
  --allocation-method Static

# Create the NAT gateway
az network nat gateway create \
  --resource-group YOUR_RG \
  --name myNatGateway \
  --public-ip-addresses myNatGatewayIP \
  --idle-timeout 10

# Associate the NAT gateway with your ACI subnet
az network vnet subnet update \
  --resource-group YOUR_RG \
  --vnet-name YOUR_VNET \
  --name YOUR_ACI_SUBNET \
  --nat-gateway myNatGateway

After this, any container group deployed into that subnet will have outbound internet connectivity via the NAT gateway's static public IP. This also gives you a predictable outbound IP for firewall allowlisting, a side benefit that's genuinely useful in enterprise scenarios.

VNet-deployed container groups can also communicate securely with on-premises resources via a VPN gateway or ExpressRoute connection on the same virtual network. If that connectivity is broken, verify the VPN gateway health and check that your subnet's route table includes the correct routes for on-premises address spaces.

Azure Container Instances requires TLS 1.2 for all secure client connections, no exceptions. TLS 1.0 and TLS 1.1 support has been retired. If your application code, an SDK it depends on, or a client tool connecting to ACI is still negotiating on an older TLS version, the handshake will fail and you'll see connection errors that can look like generic network failures if you're not looking in the right place.

The most common scenario: a legacy .NET Framework application inside the container that defaults to TLS 1.0 or 1.1 when making outbound HTTPS calls. Fix this by explicitly setting the security protocol in your application code:

// .NET, force TLS 1.2
System.Net.ServicePointManager.SecurityProtocol =
    System.Net.SecurityProtocolType.Tls12;

For Python applications using the requests library, make sure you're on a version of OpenSSL that supports TLS 1.2 in your container image. Alpine-based images sometimes ship with older OpenSSL builds. Switching to a Debian-based image (e.g., python:3.12-slim instead of python:3.12-alpine) often resolves this immediately.

For Node.js, TLS 1.2 is the default from Node 12+ onwards, so if you're on a modern base image you should be fine. If you're running something older and can't update, you can force TLS 1.2 via:

// Node.js, force TLS 1.2 minimum
const https = require('https');
const agent = new https.Agent({
  secureProtocol: 'TLSv1_2_method'
});

On the infrastructure side, if you're exposing your container group directly to the internet with a DNS name label (e.g., myapp.eastus.azurecontainer.io), make sure any load balancer, API gateway, or reverse proxy in front of it is also configured to reject TLS 1.0 and 1.1 connections from clients. The container FQDN format follows the pattern [customlabel].[region].azurecontainer.io and access always goes over HTTPS.

If you're debugging TLS issues from outside the container, the openssl s_client command is your best friend:

openssl s_client -connect YOUR_FQDN:443 -tls1_2

A successful TLS 1.2 handshake will return the certificate chain and end with Verify return code: 0 (ok). Anything else tells you exactly where the negotiation is breaking.

If you're running a multi-container setup, say, an application container alongside a logging sidecar or a data processor, and your containers can't see each other, the issue is almost always that you're not using a container group. Containers in the same ACI container group share the same host, local network, storage, and lifecycle. Containers in separate container groups are isolated from each other by default.

When deploying a multi-container group, YAML is the cleanest approach. Here's a minimal two-container group definition:

apiVersion: 2019-12-01
location: eastus
name: myContainerGroup
properties:
  containers:
  - name: app
    properties:
      image: myregistry.azurecr.io/myapp:latest
      resources:
        requests:
          cpu: 1
          memoryInGb: 1.5
      ports:
      - port: 80
  - name: logger
    properties:
      image: myregistry.azurecr.io/mylogger:latest
      resources:
        requests:
          cpu: 0.5
          memoryInGb: 0.5
  osType: Linux
  ipAddress:
    type: Public
    ports:
    - protocol: tcp
      port: 80
type: Microsoft.ContainerInstance/containerGroups

Note the osType: Linux, multi-container groups are a Linux-only feature. Windows container deployments support only a single container per group.

For persistent storage, ACI supports direct mounting of Azure Files shares. First, create the file share in your storage account, then mount it in your container definition:

az container create \
  --resource-group YOUR_RG \
  --name mycontainer \
  --image myimage:latest \
  --azure-file-volume-account-name YOUR_STORAGE_ACCOUNT \
  --azure-file-volume-account-key YOUR_STORAGE_KEY \
  --azure-file-volume-share-name myshare \
  --azure-file-volume-mount-path /mnt/data

Volume mounting (Azure Files, emptyDir, GitRepo, secret) is also Linux-only. If you're on a Windows container and wondering why the volume mount flag is being rejected, that's why. The fix is to switch to a Linux base image if your workload allows it.

One thing I always recommend: test your multi-container group locally with Docker Compose before deploying to ACI. ACI supports deploying directly from Docker Compose definitions via the Docker CLI integration, which means you can use the exact same docker-compose.yml file for local testing and cloud deployment, significantly reducing "works on my machine" problems.