Container Instances errors

Container Instances runs a container group directly, so its errors arrive at deployment time from Resource Manager (reference/arm/deployment-errors.md for the wrapper). The image pull is checked during the deployment. Microsoft.ContainerInstance/containerGroups@2026-07-01 is the newest stable API and has Bicep types.

Pulling from Container Registry with a managed identity

imageRegistryCredentials takes server plus exactly one of username/password or identity (a user-assigned identity's resource ID that is also listed in the group's identity). That identity needs AcrPull (or Container Registry Repository Reader on an ABAC-mode registry).

Code / message	Cause → fix
`InaccessibleImage` `The image '<registry>.azurecr.io/<image>:<tag>' in container group '<name>' is not accessible. Please check the image and registry credential.`	Wrong server, repository, tag or digest; the image doesn't exist; or the identity can't pull (role missing or not propagated, registry firewall). Check with `az acr repository show-tags -n <acr> --repository <repo>` and the identity's role assignments
`AmbiguousImageResitryCredentialType` `The registry credential type in the 'imageRegistryCredentials' of container group '<name>' cannot be detected. Please set exactly one of username or identity`	Both `username` and `identity` are set (the code really is misspelled "Resitry"). Remove one
`InvalidImageRegistryIdentity` `The identity in the 'imageRegistryCredentials' of container group '<name>' not found in container group identity list.`	The identity isn't assigned to the container group: add it to `identity.userAssignedIdentities`, using the same resource ID string
`InvalidImageRegistryCredentialType` `Identity in 'imageRegistryCredentials' of container group '<name>' is not supported.`	API version before 2021-07-01. Use a current API version
`InvalidRequestContent` `… Required property 'server' not found in JSON. Path 'properties.imageRegistryCredentials[0]' …`	`server` (the login server, `<acr>.azurecr.io`) is missing

Capacity, quota and rate limits

Code / message	Cause → fix
`The requested resource is not available in the location '<region>' at this moment. Please retry with a different resource request or in another location. Resource requested: '<n>' CPU '<n>' GB memory 'Linux' OS … ServiceUnavailable (409).`	The feature isn't available there, or capacity is short (usually intermittent). Groups over 4 CPU or 16 GB are "Big Container Groups" with on-demand regional capacity. Check region capabilities (Location - List Capabilities REST API), retry, try another region, or open a support case for big groups
`(ServiceUnavailable) Resource type 'Microsoft.ContainerInstance/containerGroups' container group quota 'ContainerGroups' exceeded in region '<region>'.`	Per Microsoft's article: deploying several container groups with the same name in different regions at the same time trips ACI's fraud detection (the error shows a limit of `0`), typically from automation. Deploy them one at a time
`RegistryErrorResponse` (Docker Hub image)	Docker Hub's pull rate limits (Azure's unlimited anonymous pulls ended June 30, 2024). Authenticate pulls with a Docker account, or better, pull through Container Registry's Artifact Cache

Registry-side errors: reference/container-registry/errors.md.

Runtime: restarts, exits and reachability

Symptom	Cause → fix
`OsVersionNotSupported` `The OS version of image '{0}' is not supported.`	Usually a Windows image on Semi-Annual Channel 1709 or 1803: use a supported Windows base (the ACI FAQ lists them)
The container keeps exiting and restarting	The default restart policy is `Always`, and the image (Ubuntu, Alpine) has no long-running process. Give it a command that keeps running, or use `--restart-policy OnFailure` / `Never` for run-to-completion jobs. `Never` still allows a platform restart after a nonzero exit
Restarts nobody asked for	An app crash (read `az container logs` and the events in `az container show`), or platform maintenance. Run several groups behind Application Gateway or Traffic Manager when it must stay up
Exit code 137	SIGKILL, usually the memory limit: raise the group's memory
Exit code 139	Segmentation fault; Microsoft names Ubuntu 22.04 base images: try another base
Exit codes 7147 / 7148, events `Killing container (platform initiated)`	Graceful (7147) or forced (7148, didn't stop in time after the signal) platform shutdown: maintenance, rebalancing or host updates. Handle SIGTERM quickly
The public IP stopped working after a restart	A group's IP can change on restart. Use the DNS name label (`--dns-name-label`), or a VNet deployment behind a load balancer or gateway
The IP answers nothing on the expected port	ACI has no port mapping: the app must listen on the same port the group exposes (`--ports 9000` plus the app on 9000)
Slow start	Image size and pull distance: use multi-stage builds and a registry in the same region. New Windows containers can lack network for about 30 seconds: retry at startup
Need privileged mode or the Docker API	Not offered. Use AKS or a VM