Multi-Arch Image Mismatch¶

Use this playbook when a revision pulls successfully but the container fails immediately with architecture errors such as exec format error or no matching manifest.

Symptom¶

• Image pull succeeds, but the container exits immediately.
• System or console logs show exec format error, no matching manifest, or similar architecture mismatch text.
• The same tag works on one platform but fails in Azure Container Apps.
• A single-architecture image tag was pushed where a multi-architecture manifest was expected.

Possible Causes¶

• The tag points only to an arm64 image while the target expects amd64.
• The manifest list is missing one of the required architectures.
• A previous multi-arch tag was overwritten with a single-arch image.
• The base image supports fewer architectures than the build pipeline assumed.

Diagnosis Steps¶

flowchart TD
    A[Container exits immediately after pull] --> B[Read startup and system logs]
    B --> C{exec format or manifest mismatch?}
    C -->|No| D[Use generic startup failure playbook]
    C -->|Yes| E[Inspect registry tag and manifests]
    E --> F{Required architecture present?}
    F -->|No| G[Rebuild and publish multi-arch image]
    F -->|Yes| H[Check tag drift or wrong image reference]
    G --> I[Retest deployment with explicit manifest]
    H --> J[Pin correct digest or corrected tag]

1. Capture the configured image and the observed startup error.

   az containerapp show \
       --name "$APP_NAME" \
       --resource-group "$RG" \
       --query "properties.template.containers[0].image" \
       --output tsv
   
   az containerapp logs show \
       --name "$APP_NAME" \
       --resource-group "$RG" \
       --type system
   

   Command	Why it is used
   az containerapp show ...	Reads the Container App configuration so the documented setting can be verified.

2. Inspect the registry tag and available manifests.

   az acr repository show-tags \
       --name "$ACR_NAME" \
       --repository "myapp" \
       --output table
   
   az acr manifest list-metadata \
       --name "myapp" \
       --registry "$ACR_NAME" \
       --output json
   

   Command	Purpose
   az acr repository show-tags --name "$ACR_NAME" --repository "myapp" --output table	Lists the tags that actually exist in the target repository so you can prove whether the image reference in the app points to a published tag.
   az acr manifest list-metadata --name "myapp" --registry "$ACR_NAME" --output json	Lists manifest metadata for the repository so you can confirm which platform variants were actually pushed and whether the failing tag is missing the architecture Container Apps needs.

3. Query logs for architecture-specific failure text.

   let AppName = "ca-myapp";
   ContainerAppSystemLogs_CL
   | where ContainerAppName_s == AppName
   | where TimeGenerated > ago(2h)
   | where Log_s has_any ("exec format error", "no matching manifest", "manifest unknown")
   | project TimeGenerated, RevisionName_s, Reason_s, Log_s
   | order by TimeGenerated desc
   

Resolution¶

1. Rebuild and publish the image as a multi-architecture manifest.

   docker buildx build \
       --platform linux/amd64,linux/arm64 \
       --push \
       --tag "$ACR_NAME.azurecr.io/myapp:stable" \
       .
   

2. If only one architecture is supported intentionally, publish a clearly named tag and deploy only where it matches.

3. Pin a corrected digest or tag after confirming manifest contents.
4. Prevent tag drift in CI so a multi-arch tag is not accidentally replaced by a single-arch push.

Prevention¶

• Standardize on docker buildx for production image publishing.
• Validate manifest contents in CI before deployment.
• Avoid reusing critical tags without architecture checks.
• Keep base-image architecture support documented for each workload.

See Also¶

• Image Pull Failure
• Docker Hub Rate Limit
• Image Size Startup Delay

Sources¶

• Push multi-architecture images to Azure Container Registry
• Container registries in Azure Container Apps
• Troubleshoot container start failures in Azure Container Apps