How to Troubleshoot Azure Container Instances

Why This Is Happening

I've seen this exact scenario more times than I can count , you spin up an Azure Container Instances group, the deployment says it succeeded, and then your container either sits in a Waiting state forever, crashes on startup, or exits with a cryptic non-zero code and no explanation. Azure's portal error messages are notoriously sparse. "Container group provisioning failed" tells you almost nothing useful, and that's genuinely infuriating when you're trying to ship something.

Azure Container Instances troubleshooting is tricky because ACI sits at an unusual intersection: it's a serverless compute platform, but it runs full container images. That means problems can originate from the image itself, from the Azure networking layer, from registry authentication, from resource quota limits, from your environment variable configuration, or from the container's own application logic. There's no single place to look.

The most common root causes I see fall into five buckets:

• Image pull failures , either the image tag doesn't exist, the registry is private and credentials weren't passed correctly, or Docker Hub rate-limiting kicked in.
• Container startup crashes, the application inside the container exits immediately because it can't find an expected environment variable, a required port binding fails, or a mounted volume path doesn't exist.
• Networking misconfiguration, especially in VNet-injected container groups where DNS resolution breaks, or where a subnet doesn't have the Microsoft.ContainerInstance/containerGroups service delegation applied.
• Resource exhaustion, the container is hitting its CPU or memory ceiling and getting OOM-killed (event code OOMKilled) without any obvious indication in the portal.
• Restart policy or exit code confusion, containers configured with Always restart policy that exit with code 0 (success) still restart, causing a loop that looks like a crash but isn't.

What makes Azure Container Instances troubleshooting especially frustrating is that the provisioning state and the container state are two separate things. Your container group can be in Succeeded provisioning state while the container itself is in Terminated with exit code 137. Microsoft's portal doesn't always surface this clearly. I'll show you exactly where to look.

Browse all Microsoft fix guides →

The Quick Fix, Try This First

Before you go deep into logs and registry settings, run this Azure CLI command. It gives you everything diagnostic in one shot and saves at least 20 minutes of clicking around the portal:

az container show \
  --resource-group <your-rg> \
  --name <your-container-group> \
  --query "containers[*].{Name:name, State:instanceView.currentState, PrevState:instanceView.previousState, RestartCount:instanceView.restartCount}" \
  --output table

This single query shows you the current container state, the previous state (which often tells you more than the current one), and the restart count. If restart count is above 0, you have a crash loop. If current state is Terminated with an exit code, that exit code is your primary diagnostic signal.

Then immediately pull the logs:

az container logs \
  --resource-group <your-rg> \
  --name <your-container-group> \
  --container-name <your-container-name>

If the container started and then crashed, its stdout/stderr output will be here. In my experience, about 60% of Azure Container Instances issues are fully diagnosed from these two commands alone. The container itself is usually telling you exactly what's wrong, a missing env var, a port conflict, a failed database connection, but nobody reads the logs first.

If logs come back empty or the container never started at all, that points to an image pull problem or a networking issue at the infrastructure level. In that case, move directly to Step 2 (image pull diagnostics) in the step-by-step section below.

For containers stuck in Waiting state for more than 3–4 minutes: that's almost always a private registry authentication failure or a VNet subnet delegation issue. Neither shows up as a helpful error in the portal, I'll cover both precisely in the steps below.

Advanced Troubleshooting

When the standard steps above don't solve the problem, you're usually dealing with one of several more obscure scenarios. Here's what I reach for after the basics are exhausted.

Using az container exec for Live Debugging

If your container is running but behaving incorrectly, you can exec into it directly, similar to docker exec:

az container exec \
  --resource-group <your-rg> \
  --name <your-container-group> \
  --container-name <your-container> \
  --exec-command "/bin/sh"

From inside the container, you can test DNS resolution with nslookup, check environment variables with env, verify file mounts with ls -la, and test outbound connectivity with curl. This is invaluable for debugging ACI networking issues that are otherwise invisible from outside.

Container Group ARM Template Validation

Malformed ARM templates are a common but non-obvious source of deployment failures. The portal error for a bad template is often just "deployment failed" with no detail. Export your current container group as an ARM template and validate it:

az container export \
  --resource-group <your-rg> \
  --name <your-container-group> \
  --file container-group.yaml

Then use az deployment group validate before re-applying. Look specifically for invalid osType values, mismatched resource limits between containers and the group level, and GPU SKU requests in regions that don't support them.

Service Principal and Managed Identity Issues

If your container is trying to authenticate against Azure services (Key Vault, Storage, Service Bus) using a managed identity and getting 401 or 403 errors, verify the identity is actually assigned:

az container show \
  --resource-group <your-rg> \
  --name <your-container-group> \
  --query identity

If it returns null, the identity wasn't assigned at deployment time. Also check that the identity has the required RBAC role on the target resource, ACI containers frequently get the identity assigned but the role assignment on the downstream resource is forgotten.

Azure Policy Blocking Deployment

In enterprise environments, Azure Policy can silently block ACI deployments that don't meet compliance requirements, for example, policies requiring all containers to use approved base images, or policies blocking privileged containers. Check the Activity Log for your resource group and look for any PolicyViolation events in the same time window as your deployment attempt. Navigate to your resource group → Activity log → filter by time range and look for Microsoft.ContainerInstance/containerGroups/write with a Failed status.

Region-Specific Quota Limits

ACI has per-subscription, per-region quotas. If you're getting provisioning errors with no clear cause, check your quota:

az container list-usage --location <your-region> --output table

Common limits that get hit: maximum container groups per region (100 by default), maximum CPU cores per region, and GPU container limits. Submit a support request to increase quotas, they're usually approved within 1–2 business days.

Prevention & Best Practices

Most Azure Container Instances issues I see are preventable. After enough of these debugging sessions, you develop habits that short-circuit the entire class of problems before they happen in production.

The biggest one: test your image locally against the exact same environment variables and resource constraints before deploying to ACI. Run it with docker run --memory="1.5g" --cpus="1" to simulate ACI's default limits. If it crashes locally under those constraints, it'll crash in ACI too, and at least locally you have easy access to logs and interactive debugging.

Second, use Azure Container Registry rather than Docker Hub for all production images. ACR integrates natively with ACI via managed identity (no credentials to manage), geo-replicates if needed, and doesn't have rate limits. The Docker Hub rate limit issue is completely avoidable.

Third, structure your container images to fail fast and loudly. If a required environment variable is missing, your entrypoint script should print a clear error message and exit with a non-zero code immediately, not silently continue and fail in a confusing way ten seconds later. Something like:

#!/bin/sh
: "${DATABASE_URL:?DATABASE_URL is required but not set. Exiting.}"
: "${API_KEY:?API_KEY is required but not set. Exiting.}"
exec "$@"

Fourth, tag your images with meaningful version tags, never just :latest. The :latest tag is a notorious source of ACI container image pull errors, it can change underneath you between deployments and makes rollbacks nearly impossible to reason about.

Finally, set up Log Analytics integration from day one, not after the first production incident. The cost is minimal and having historical log data available when something goes wrong is invaluable for ACI container crash loop analysis and post-incident review.

Frequently Asked Questions