Skip to content

Fix: Docker: Invalid reference format

  • by
  • 2 min read

Docker is a rather useful thing for higher-level developers, but as easy as it is, it can sometimes run into rather annoying bugs and glitches that can leave even the most experienced developers scratching their heads. 

In this article, we’re talking about the “Docker: invalid reference format” error, its causes and what you can do to fix the problem.

What causes the “Docker: invalid reference format” error?

Three main causes can trigger the error:

  • Docker image has uppercase letters in the name
  • Incorrect build command syntax
  • Long build command isn’t separated properly

Also read: What is Docker? How is it different from VM?

How to fix “Docker: invalid reference format” error?

Here are three fixes you can try out. 

Check the Docker image name

As mentioned above, the Docker image name can’t have uppercase characters. If your Docker image file does have uppercase characters in the name, it won’t be properly parsed when you run the build command leading to errors like this. Check the file name and ensure that it doesn’t have any uppercase letters before issuing the build command to see if that fixes the problem.

Top 7 IDEs and Text Editors to code Python, Java, C++, HTML and more

Check command syntax

Another common reason why you’ll run into this error is that the syntax isn’t right. Based on whether you’re running the command in bash or powershell, you’re required to use different characters. 

  • Bash: The command should run with $(pwd). For example:
docker run -p 1234:5678 -v `$(pwd)` /...
  • Powershell: The command should run with ${pwd}. For example:
docker run -p 1234:5678 -v `${pwd}` /...

Check command separators

Last, check to see if the command has the correct separators. Long terminal commands are often broken up into multiple lines. However, based on the terminal they’re running in, the actual separators breaking them into different lines should be different. 

  • Command Prompt: Use ^
  • Powershell: Use `
  • Bash: Use empty space 

Also read: How to fix Docker exec format error? 


Yadullah Abidi

Yadullah is a Computer Science graduate who writes/edits/shoots/codes all things cybersecurity, gaming, and tech hardware. When he's not, he streams himself racing virtual cars. He's been writing and reporting on tech and cybersecurity with websites like Candid.Technology and MakeUseOf since 2018. You can contact him here: [email protected].