Solving docker: invalid reference format error – Code Example

There are many reasons for docker to throw invalid reference format error. Invalid reference means that the variables, paths, shortcuts etc. are not pointing towards a valid resource. Docker throws this error because the references we used in commands have errors. In this article we will discuss about common mistakes we do while creating docker command.

Reasons of docker invalid reference error

These are the most common reasons –

1. Using pwd without quotes.
2. Referencing pwd wrongly in Windows Powershell.
3. Invalid characters in commands like en dash (–) instead of hyphen (-)
4. Some environment variable is not set
5. Using wrong encoding like CRLF in shell files
6. Running multi line command in one line without removing \

Let’s understand all these reasons one by one.

Using pwd without quotes

pwd stands for present working directory. This is very handy variable because you don’t need to fix your path. If you want to move your project directory to another location then pwd will return the path of that location.

Since pwd represents the absolute path, it will get replaced by path in the commands like this –

$(pwd)/hello

# replaced as -

/path/to/the/present/working/directory/hello

Suppose there is a space in the path then it will break the command and you will never know because you used pwd. Something like this –

$(pwd)/hello

# as -
# Broken here  👇
#         ______|_______
#        |              |
/path/to/present working/directory/hello

You have two solutions here – First, have no space in directories; Second, enclose the path in quotes. Like this –

# This is fine

"/path/to/present working/directory/hello"

So, you need to enclose the pwd in quotes –

"$(pwd)/hello"

Referencing pwd wrongly in Windows Powershell

In powershell if you are referencing pwd using $pwd or $(pwd) then it might not work. Else use this –

${pwd}

Invalid characters in commands like en dash (–) instead of hyphen (-)

Suppose you are running this command –

docker run –it nginx

It will raise invalid reference format error. But the command looks absolutely correct then why? Because in the it flags, we used en dash (–) instead of hyphen (-).

Character system in computers has a long range. But only few of them are standard. Many resembles each other and it’s hard to distinguish from naked eyes.

Then how can you know about it? You can use an online special character encoder and check your command through it. If it generates unfamiliar character codes then it means your command is using non-standard characters.

But these special characters are not on keyboards then how they get inserted into commands? Well it happens due to copy-pasting codes from websites on internet. Sometimes plugins, frameworks and editors converts standard characters into non-standard characters to improve the look & feel. For example a hyphen is shorter in length so an editor can automatically convert it into en dash to improve the visibility. But that will not work in codes.

The solution to this problem is to write the commands by yourself. If you write it, there is no chance of inserting non-standard characters until and unless you deliberately wants to include them.

Some environment variable is not set

If an environment variable is not set and yet you use it in your command then what will happen? That variable will be replaced by empty string. An empty string means something missed which you wanted to be in your command. Check this example –

docker run -it ${image}

Here we are using an environment variable image. But if it’s not set then our command will become this –

docker run -it 

The command broke because there is no image for docker to run. This will result in reference format error.

The solution to this problem is to make sure if the environment variables are set before running your commands.

Using wrong encoding like CRLF in shell files

A file has 3 different encodings depending upon operating systems like –

• Windows – CRLF
• MacOs – CR
• Linux – LF

If you are running docker then it will run in linux virtual machine so all the executable files like shell scripts will need to be in LF encoding.

If you put the docker commands in shell script and created that script in windows text editor then most probably it has taken CRLF encoding. When you run it in WSS terminal, it will raise reference error.

The solution to this problem is to change the encodings to LF in all shell scripts.

Running multi line command in one line without removing \

How many times does this happens that we copy a code from website like StackOverflow and change its indentation, spaces, and new lines? A lot, right? Most of the times that is not an issue but sometimes it is. Like in Python, indentation plays a very important role. Same goes with YAML files.

Similarly in linux commands, a multi line is written differently than a single line. In multiline command we use \. In single line we don’t need to.

The \ indicates that the command is not complete and it is extended to next line. If we are not using the next line then there is no meaning to add \. And if you are using it unnecessarily then that’s an error. Check this code –

docker run --name myproject \
-e API_KEY="MY_KEY" \
myproject:latest

The above code is fine but if you are writing it in single line without removing \ like this code –

docker run --name myproject \ -e API_KEY="MY_KEY" \ myproject:latest

then it will raise invalid reference format error. The correct command will be –

docker run --name myproject -e API_KEY="MY_KEY" myproject:latest

Conclusion

In this article we saw a number of reasons for docker to raise invalid reference format error. We worked over their solutions one by one. If you are facing this issue then first check which reason is matching your case. Once that is identified then you can apply the appropriate solutions described.