What causes DOCKER_IMAGE_PULL_FAILURE?

The container registry credentials stored in Databricks are expired or incorrect. The Docker image tag or repository path is incorrect in the cluster configuration. The container registry is private and the Databricks cluster nodes cannot reach it (network issue). The image was deleted from the registry. The registry rate limit was exceeded (e.g., Docker Hub pull limit)

How do I fix DOCKER_IMAGE_PULL_FAILURE?

Verify the Docker image URL and tag in the cluster configuration. Update the container registry credentials in the Databricks secret store or cluster configuration. Test that the cluster subnet can reach the container registry (check firewall and NAT gateway rules). Pull the image manually from a VM in the same subnet to isolate the connectivity issue. If using Docker Hub, switch to a private registry or Databricks Container Services to avoid rate limits

High severitycluster

Power BI Refresh Error:
DOCKER_IMAGE_PULL_FAILURE

What does this error mean?

The Databricks cluster failed to pull the Docker container image from the configured container registry. Clusters using custom Docker images cannot start until the image is successfully downloaded.

Common causes

1The container registry credentials stored in Databricks are expired or incorrect
2The Docker image tag or repository path is incorrect in the cluster configuration
3The container registry is private and the Databricks cluster nodes cannot reach it (network issue)
4The image was deleted from the registry
5The registry rate limit was exceeded (e.g., Docker Hub pull limit)

How to fix it

1Verify the Docker image URL and tag in the cluster configuration
2Update the container registry credentials in the Databricks secret store or cluster configuration
3Test that the cluster subnet can reach the container registry (check firewall and NAT gateway rules)
4Pull the image manually from a VM in the same subnet to isolate the connectivity issue
5If using Docker Hub, switch to a private registry or Databricks Container Services to avoid rate limits

Frequently asked questions

Does this affect clusters using the default Databricks Runtime?

No — DOCKER_IMAGE_PULL_FAILURE only affects clusters configured with a custom Docker container image.

Where are container registry credentials stored in Databricks?

In the cluster configuration under 'Docker' settings or in a Databricks secret scope referenced by the cluster init script.