Problem: docker says "invalid reference format" / "repository name must be lowercase" —— Trove problem library

What you will run into

docker run / docker pull fails immediately with docker: invalid reference format: repository name (library/Ubuntu) must be lowercase, or just the bare docker: invalid reference format.

The image exists and the network is fine — the string you typed does not match Docker's image-name grammar. Most common: an uppercase repository name, a stray space inside quotes, or an unexpanded variable (like ${pwd} in PowerShell).

Why this happens

An image reference has a strict grammar: [registry/]name[:tag]. Repository names allow only lowercase letters, digits and -_.; tags allow letters, digits, _, -, ..

Any character outside the grammar makes the daemon refuse to parse it and report invalid reference format.

Typical failure points:

The docker CLI parses the <image> argument into a "repository + tag + digest" triple *before any network request*. A parse failure is a purely local string check — it has nothing to do with the daemon, mirrors or the network.

That is what makes this error misleading: it looks like a network problem but is a string problem.

Deterministic takeaway: when you see it, print the exact image string the command received (echo "$IMAGE") and inspect spaces/case/unexpanded variables; the only rule you need: repository lowercase, no spaces.

Step by step

1. Print the final image name — Must do

echo "ubuntu "     # you will see the trailing space
echo "$TAG"        # is the variable empty or containing invalid chars?

2. Branch on the error form — By diagnosis

• Error includes repository name (library/Ubuntu) must be lowercase → uppercase in the repository: lowercase it (Ubuntu → ubuntu).
• Bare invalid reference format → likely a space or an empty string: remove stray spaces inside quotes, or echo the variable expansion first.
• Variable case: in PowerShell ${pwd} is the "current path string", not the result of $(pwd) — use $(pwd) (PowerShell) or ${PWD} (bash), or expand into a variable first.

3. Confirm with a minimal command — Must do

docker run alpine echo ok   # lowercase + no space works → your original string was malformed

How to confirm it works

docker run alpine echo ok prints ok with no invalid reference format; the corrected original command pulls/starts normally.

Other environments

Symptom

# Form 1: uppercase repository (full text)
docker: invalid reference format: repository name (library/Ubuntu) must be lowercase

# Form 2: space in the string (short form)
docker: invalid reference format

Run 'docker run --help' for more information

Signature: docker run / docker pull fails immediately with exit 125, no network involved; the command string has uppercase/space/unexpanded variables.

Cause

Image references have a strict grammar: repository names allow only lowercase letters, digits and -_.; tags allow [A-Za-z0-9_][A-Za-z0-9_.-]{0,127}. Spaces, uppercase repositories and unexpanded variables fail local parsing before any network request — unrelated to daemon/mirror/network.

Solution

1. echo the final image name; check for spaces, case and variable expansion;
2. Lowercase the repository; remove stray spaces inside quotes; expand variables correctly ($(pwd) in PowerShell, ${PWD} in bash);
3. docker run alpine echo ok to prove the syntax layer works, then retry your original command.

Related canonicals

Read in order: precondition -> same root / same domain / related:

• Related (similar errors, different cause):
• Docker daemon unreachable (make sure the daemon is alive first; connection errors surface before reference parsing)