Docker Hub Rate Limit¶

Use this playbook when new revisions fail to start or scale-out events fail intermittently because Docker Hub anonymous pull limits are exhausted.

Symptom¶

• System logs show image pull failures with toomanyrequests or similar pull-rate messages.
• Revisions fail during provisioning even though the image name and tag are correct.
• The same image may work at low frequency but fail during repeated deployments or burst scale-out.
• Pull failures disappear temporarily after waiting for the registry limit window to reset.

Possible Causes¶

• The app pulls from Docker Hub without authenticated registry credentials.
• Multiple revisions or environments share the same anonymous pull budget.
• Scale-out after idle or deployment retries causes repeated image pulls in a short interval.
• The workload depends on public base images that are not mirrored into a controlled registry.

Diagnosis Steps¶

flowchart TD
    A[Image pull fails during revision start] --> B[Read system log error]
    B --> C{Error contains toomanyrequests?}
    C -->|No| D[Use Image Pull Failure playbook instead]
    C -->|Yes| E[Check image registry and auth configuration]
    E --> F{Authenticated Docker Hub or mirrored registry configured?}
    F -->|No| G[Anonymous pull rate limit is likely]
    F -->|Yes| H[Check credentials, retries, and image source]
    G --> I[Add registry credentials or mirror image into ACR]
    H --> J[Retest with controlled pull source]

1. Confirm the configured image source and capture the system log message.

   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
   

1. Review registry configuration for the app.

   az containerapp show \
       --name "$APP_NAME" \
       --resource-group "$RG" \
       --query "properties.configuration.registries" \
       --output json
   

   Command	Purpose
   az containerapp show --name "$APP_NAME" --resource-group "$RG" --query "properties.configuration.registries" --output json	Reads the app's registry configuration so you can tell whether the Docker Hub image is being pulled anonymously or through an alternate registry/auth configuration before blaming rate limiting.

2. Search for repeated rate-limit errors during deployment or scale-out windows.

   let AppName = "ca-myapp";
   ContainerAppSystemLogs_CL
   | where ContainerAppName_s == AppName
   | where TimeGenerated > ago(2h)
   | where Log_s has_any ("toomanyrequests", "rate limit", "pull rate limit")
   | project TimeGenerated, RevisionName_s, Reason_s, Log_s
   | order by TimeGenerated desc
   

Resolution¶

1. Add authenticated registry credentials if you must pull directly from Docker Hub.
2. Prefer mirroring the image into Azure Container Registry so deployments and scale-out use a controlled source.
3. Reduce unnecessary revision churn while validating the fix.

4. Re-deploy only after registry configuration is updated.

   az containerapp registry set \
       --name "$APP_NAME" \
       --resource-group "$RG" \
       --server "index.docker.io" \
       --username "<docker-hub-username>" \
       --password "<docker-hub-access-token>"
   

   Command	Why it is used
   az containerapp registry set ...	Runs the Azure CLI operation required by the documented step.

Prevention¶

• Treat public Docker Hub pulls as an external dependency with rate risk.
• Mirror production images into ACR before high-frequency deployment or scale testing.
• Use stable image references and avoid repeated failed retries against the same public source.
• Document which apps still depend on public registry pulls.

See Also¶

• Image Pull Failure
• Image Size Startup Delay
• Multi-Arch Image Mismatch

Sources¶

• Container registries in Azure Container Apps
• Troubleshoot container start failures in Azure Container Apps
• Authentication with Azure Container Registry