---
id: bed2ff11-488a-497d-b87d-8b58cc50681e
---

# Docker Image Pull Failure.
---

A Docker Image Pull Failure is an incident where the Docker engine fails to download a specific image from a container registry. This issue can occur due to various reasons such as network connectivity issues, authentication problems, or server-side errors. As a result of this failure, the container that requires the specific image fails to start or run, causing a disruption in the application or service that relies on that container.

### Parameters
```shell
export REGISTRY_URL="PLACEHOLDER"

export IMAGE_NAME="PLACEHOLDER"

export DOCKER_REGISTRY_HOSTNAME_OR_IP_ADDRESS="PLACEHOLDER"

export DOCKER_REGISTRY_PORT_NUMBER="PLACEHOLDER"

export DOCKER_REGISTRY_PASSWORD="PLACEHOLDER"

export DOCKER_REGISTRY_USERNAME="PLACEHOLDER"

export DOCKER_REGISTRY_URL="PLACEHOLDER"
```

## Debug

### Check Docker network connectivity
```shell
docker run --rm alpine ping ${REGISTRY_URL}
```

### Check Docker daemon status
```shell
systemctl status docker
```

### Check Docker version
```shell
docker version
```

### View Docker image details
```shell
docker image inspect ${IMAGE_NAME}
```

### View Docker logs
```shell
journalctl -u docker.service
```

### Check Docker image tags
```shell
curl -s https://${REGISTRY_URL}/v2/${IMAGE_NAME}/tags/list
```

### Test Docker image pull
```shell
docker pull ${IMAGE_NAME}
```

### Authenticate Docker registry login
```shell
docker login ${REGISTRY_URL}
```

### Check Docker credentials
```shell
cat ~/.docker/config.json
```

## Repair

### Check the network connectivity between the Docker engine and the container registry to ensure that there are no network issues.
```shell
bash

#!/bin/bash



# Setting variables

DOCKER_REGISTRY=${DOCKER_REGISTRY_HOSTNAME_OR_IP_ADDRESS}

DOCKER_REGISTRY_PORT=${DOCKER_REGISTRY_PORT_NUMBER}



# Ping the Docker registry to check network connectivity

ping -c 3 $DOCKER_REGISTRY



if [[ $? -ne 0 ]]; then

  echo "Error: Unable to connect to the Docker registry at $DOCKER_REGISTRY:$DOCKER_REGISTRY_PORT"

  exit 1

fi



echo "Success: Network connectivity between Docker engine and registry is established."

exit 0


```

### Verify that the container registry credentials are correct and that the Docker engine has the necessary privileges to access the images stored in the registry.
```shell


#!/bin/bash



# Set the required parameters

DOCKER_REGISTRY=${DOCKER_REGISTRY_URL}

DOCKER_USERNAME=${DOCKER_REGISTRY_USERNAME}

DOCKER_PASSWORD=${DOCKER_REGISTRY_PASSWORD}



# Validate the Docker registry credentials

docker login -u "$DOCKER_USERNAME" -p "$DOCKER_PASSWORD" "$DOCKER_REGISTRY"



# Check the Docker engine privileges

docker pull ${IMAGE_NAME}



# Verify if the image has been successfully pulled

if [ $? -eq 0 ]; then

  echo "Image pulled successfully from Docker registry."

else

  echo "Error: Failed to pull the image from Docker registry."

fi


```

A Docker Image Pull Failure is an incident where the Docker engine fails to download a specific image from a container registry. This issue can occur due to various reasons such as network connectivity issues, authentication problems, or server-side errors. As a result of this failure, the container that requires the specific image fails to start or run, causing a disruption in the application or service that relies on that container.


```shell
export REGISTRY_URL="PLACEHOLDER"

export IMAGE_NAME="PLACEHOLDER"

export DOCKER_REGISTRY_HOSTNAME_OR_IP_ADDRESS="PLACEHOLDER"

export DOCKER_REGISTRY_PORT_NUMBER="PLACEHOLDER"

export DOCKER_REGISTRY_PASSWORD="PLACEHOLDER"

export DOCKER_REGISTRY_USERNAME="PLACEHOLDER"

export DOCKER_REGISTRY_URL="PLACEHOLDER"
```


### Check Docker network connectivity

```shell
docker run --rm alpine ping ${REGISTRY_URL}
```

### Check Docker daemon status

```shell
systemctl status docker
```

### Check Docker version

```shell
docker version
```

### View Docker image details

```shell
docker image inspect ${IMAGE_NAME}
```

### View Docker logs

```shell
journalctl -u docker.service
```

### Check Docker image tags

```shell
curl -s https://${REGISTRY_URL}/v2/${IMAGE_NAME}/tags/list
```

### Test Docker image pull

```shell
docker pull ${IMAGE_NAME}
```

### Authenticate Docker registry login

```shell
docker login ${REGISTRY_URL}
```

### Check Docker credentials

```shell
cat ~/.docker/config.json
```


### Check the network connectivity between the Docker engine and the container registry to ensure that there are no network issues.

```shell
bash

#!/bin/bash



# Setting variables

DOCKER_REGISTRY=${DOCKER_REGISTRY_HOSTNAME_OR_IP_ADDRESS}

DOCKER_REGISTRY_PORT=${DOCKER_REGISTRY_PORT_NUMBER}



# Ping the Docker registry to check network connectivity

ping -c 3 $DOCKER_REGISTRY



if [[ $? -ne 0 ]]; then

  echo "Error: Unable to connect to the Docker registry at $DOCKER_REGISTRY:$DOCKER_REGISTRY_PORT"

  exit 1

fi



echo "Success: Network connectivity between Docker engine and registry is established."

exit 0


```

### Verify that the container registry credentials are correct and that the Docker engine has the necessary privileges to access the images stored in the registry.

```shell


#!/bin/bash



# Set the required parameters

DOCKER_REGISTRY=${DOCKER_REGISTRY_URL}

DOCKER_USERNAME=${DOCKER_REGISTRY_USERNAME}

DOCKER_PASSWORD=${DOCKER_REGISTRY_PASSWORD}



# Validate the Docker registry credentials

docker login -u "$DOCKER_USERNAME" -p "$DOCKER_PASSWORD" "$DOCKER_REGISTRY"



# Check the Docker engine privileges

docker pull ${IMAGE_NAME}



# Verify if the image has been successfully pulled

if [ $? -eq 0 ]; then

  echo "Image pulled successfully from Docker registry."

else

  echo "Error: Failed to pull the image from Docker registry."

fi


```


Docker Image Pull Failure.

Overview

Parameters

Debug

Check Docker network connectivity

Check Docker daemon status

Check Docker version

View Docker image details

View Docker logs

Check Docker image tags

Test Docker image pull

Check Docker credentials

Repair

Check the network connectivity between the Docker engine and the container registry to ensure that there are no network issues.

Verify that the container registry credentials are correct and that the Docker engine has the necessary privileges to access the images stored in the registry.

Learn more

Related Runbooks

Support