In this tutorial, we will learn what this error means, why it occurs, and how you can resolve it in your Docker usage.
What is an Image Reference in Docker?
In Docker, an image reference refers to a method of identifying and locating a specific Docker image within the Docker registry (Docker Hub) or the local Docker host.
By default, the image reference is comprised of two main components:
Repository – The first part defines the repository for the target image. This is the top-level organizational unit for Docker image, mainly used to represent the organization or the individual managing the image. For example, you can find an image named Microsoft/SQL-server. In this case, the first part represents the organization maintaining the image.
Tag – The second part of an image is a label associated with the specific version or variant of the image within the repository. Image tags can represent different versions of the same image, different releases, or different compatibility. For example, in the image of nginx:latest where the latest tag refers to the latest version of the Nginx image.
When specifying the image in either a Dockerfile or docker command, the image name must follow the following naming rules:
- The repository name should be lowercase.
- The repository can also contain letters, numbers, hyphens (-), underscores (_), or forward slashes (/) to indicate organization or grouping within a registry.
- No whitespace characters (spaces or tabs) should be in the image name.
Docker Invalid Reference Format
When you get the “invalid reference format” error when running the Dockerfile or Docker command, it means your name has not adhered to the above rules.
An example is as shown:
If we run the above command, it will return an error as shown:
invalid reference format: repository name must be lowercase
In this case, it tells us that the image name format is incorrect, as the image name should always be lowercase.
How To Fix the Docker Invalid Reference Format Error
As you can guess, the first method is ensuring the image reference format is correct. This includes verifying that the image name is valid.
For example, in the above command, we can fix the error by specifying the image name as:
In this case, the command should pull the latest version of the Busybox image.
Method 2 – Split Long Docker Commands
In some other cases, you might encounter the “invalid reference format” error when running a long Docker command.
In such a case, splitting the command into multiple lines is good practice. The method of command splitting will depend on your shell and system.
- However, for Bash shell, use the multiline escape character or backslash (\).
- For PowerShell, you can use the backtick character (`).
- Finally, if you are on Command Prompt, you can use a caret character as ^
For example, on Bash, run the command as:
-it \
busybox \
sh
On PowerShell, you can run the command as shown:
-it `
busybox `
sh
And lastly, if you are on the Command Prompt, use the command as shown:
-it ^
busybox ^
sh
Method 3 – ${pwd} AND $(pwd) path
Another common cause of this error is when using the ${pwd} variable. This can cause conflict, depending on the type of shell on which you are executing the said command.
In the case of PowerShell, you need to use the ${pwd} variable instead of $(pwd).
As you can guess, in the case of Bash, use the parenthesis format instead of the curly-braced input as $(pwd).
Conclusion
This post discussed the leading causes of the “invalid reference format” when working with Dockerfile or docker commands. We also explored three main methods you can use to fix this issue.
