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.

Never debug

GitLab CI

manually again

Let Dr. Droid create custom investigation plans for your infrastructure.

Book Demo
Automate Debugging for
GitLab CI
See how Dr. Droid creates investigation plans for your infrastructure.

MORE ISSUES

Made with ❤️ in Bangalore & San Francisco 🏢

Doctor Droid