Home » [FIXED] Error 'invalid reference format' in Docker
Systems & Servers

[FIXED] Error 'invalid reference format' in Docker

Read time: 3 min Updated: 2026-08-18
✨ Quick Answer

The error docker: invalid reference format (or invalid reference format: repository name must be lowercase) occurs when executing docker run, docker pull, or docker build commands with malformed quotes, uppercase characters in image names, or invalid volume syntax (-v).

Quick Diagnostics

Cause
Syntax error in image name or flags of docker run command
Solution
Ensure image tag is lowercase and free of illegal characters
Cause
Unquoted volume mount paths containing spaces
Solution
Enclose paths in quotes: -v "/local path:/container path"

The error docker: invalid reference format (or invalid reference format: repository name must be lowercase) occurs when executing docker run, docker pull, or docker build commands with malformed quotes, uppercase characters in image names, or invalid volume syntax (-v).

Quick Solution (1 Minute):

  1. Ensure image names use lowercase letters exclusively (my-app:latest, not My-App:latest).
  2. On Windows PowerShell, use "${PWD}" quotes instead of '$(pwd)'.

🚀 Step-by-Step Fixes

Step 1: Use Lowercase Repository & Image Names

Docker strictly enforces lowercase names for image repositories:

  • ❌ Incorrect: docker run -d MyCompany/Backend:v1
  • ✅ Correct: docker run -d mycompany/backend:v1

Step 2: Fix Volume Mounting Syntax Across OS Shells

Copying Linux commands directly into Windows shell environments often triggers this error:

  • Linux / macOS (Bash / Zsh):
    BASH 
    docker run -v $(pwd):/app my-image:latest
  • Windows PowerShell:
    POWERSHELL 
    docker run -v "${PWD}:/app" my-image:latest
  • Windows CMD:
    CMD 
    docker run -v "%cd%:/app" my-image:latest

Step 3: Check Multiline Backslash Escapes

In multiline shell scripts, trailing whitespace after a backslash \ breaks the command:

BASH 
docker run -d \
  --name my-container \
  -p 8080:80 \
  nginx:alpine

Ensure no spaces follow any trailing \ escape character.

Prevention Advice

Recommended security practices: