GitLab CI Docker Image Not Found

The specified Docker image in the job does not exist or is not accessible.

Understanding GitLab CI

GitLab CI/CD is a powerful tool integrated within GitLab that automates the software development lifecycle. It allows developers to build, test, and deploy their code efficiently. By defining a .gitlab-ci.yml file, teams can specify the stages, jobs, and scripts to be executed in their CI/CD pipeline.

Identifying the Symptom

One common issue encountered in GitLab CI is the 'Docker Image Not Found' error. This error typically manifests when a job in the pipeline attempts to pull a Docker image that is either incorrectly specified or unavailable. The error message might look something like this:

ERROR: Job failed: image pull failed: manifest for registry.example.com/my-image:latest not found

Exploring the Issue

Why Does This Happen?

The 'Docker Image Not Found' error occurs when the specified Docker image cannot be located in the registry. This can happen due to a typo in the image name, an incorrect tag, or the image not being pushed to the registry.

Common Scenarios

  • The image name or tag is misspelled in the .gitlab-ci.yml file.
  • The Docker image has not been pushed to the specified registry.
  • Access permissions to the registry are not correctly configured.

Steps to Fix the Issue

Verify the Docker Image Name

Ensure that the Docker image name and tag specified in your .gitlab-ci.yml file are correct. Double-check for typos or incorrect tags. For example:

image: registry.example.com/my-image:latest

Make sure that 'my-image' and 'latest' are correct and exist in the registry.

Check the Docker Registry

Log in to your Docker registry and verify that the image exists. You can use the Docker CLI to list images:

docker images

If the image is missing, ensure it is built and pushed to the registry:

docker build -t registry.example.com/my-image:latest .
docker push registry.example.com/my-image:latest

Review Access Permissions

Ensure that your GitLab CI runner has the necessary permissions to access the Docker registry. This may involve setting up authentication credentials in your GitLab CI/CD settings. Refer to the GitLab documentation for more details on configuring registry access.

Conclusion

By carefully verifying the Docker image name, ensuring the image is available in the registry, and checking access permissions, you can resolve the 'Docker Image Not Found' error in GitLab CI. For further reading, consult the GitLab CI Docker documentation.

Master

GitLab CI

in Minutes — Grab the Ultimate Cheatsheet

(Perfect for DevOps & SREs)

Most-used commands
Real-world configs/examples
Handy troubleshooting shortcuts
Your email is safe with us. No spam, ever.

Thankyou for your submission

We have sent the cheatsheet on your email!
Oops! Something went wrong while submitting the form.

GitLab CI

Cheatsheet

(Perfect for DevOps & SREs)

Most-used commands
Your email is safe with us. No spam, ever.

Thankyou for your submission

We have sent the cheatsheet on your email!
Oops! Something went wrong while submitting the form.

MORE ISSUES

Made with ❤️ in Bangalore & San Francisco 🏢

Doctor Droid