Docker: 'invalid container name ...: only [a-zA-Z0-9][a-zA-Z0-9_.-] are allowed'

invalid container name (fix8-d3 web): only [a-zA-Z0-9][a-zA-Z0-9_.-] are allowed — the value of --name holds a character Docker does not accept in a container name, here a space. Replace it with a hyphen, an underscore or a dot and run the command again.

The hint in the message is the rule: the first character is a letter or a digit, and the rest are letters, digits, _, . or -. A space and a slash both failed in this test; fix8-d3-web worked.

The error

PS> docker run --rm --name 'fix8-d3 web' alpine echo ok
docker: Error response from daemon: invalid container name (fix8-d3 web): only [a-zA-Z0-9][a-zA-Z0-9_.-] are allowed
System.Management.Automation.RemoteException
Run 'docker run --help' for more information
PS> docker run --rm --name fix8-d3/web alpine echo ok
docker: Error response from daemon: invalid container name (fix8-d3/web): only [a-zA-Z0-9][a-zA-Z0-9_.-] are allowed
System.Management.Automation.RemoteException
Run 'docker run --help' for more information

Both commands exited with code 125. The System.Management.Automation.RemoteException lines come from the Windows PowerShell 5.1 capture of Docker's error output, not from Docker.

Why it happens

The message is the Docker engine's answer ("Error response from daemon"), and it quotes the name it received in parentheses. That makes it easy to see what went wrong: a space from a quoted value, as in the first command, or a slash from a name copied out of an image reference such as team/app, as in the second. The bracketed expression after "only" lists what is allowed: [a-zA-Z0-9] for the first character, then [a-zA-Z0-9_.-] for the rest.

When the name comes from a variable in a script, a space or a slash is easy to miss. Printing the variable, or reading the name in the parentheses of the message, shows the character to replace.

The fix

PS> docker run --rm --name fix8-d3-web alpine echo ok
ok

With the space replaced by a hyphen the container ran, printed ok and was removed by --rm; docker ps -a --filter name=fix8-d3 --format '{{.Names}}' printed nothing afterwards. An underscore or a dot are the other separators the hint allows. If you build names from a path or an image name in a script, replace the slash before passing the value to --name.

How it was reproduced

docker run --rm --name with a name containing a space, then one containing a slash, on the cached alpine image, from Windows PowerShell 5.1 on Docker Engine 29.9.2 (Docker Desktop on Windows 11). The fix8-d3 names are this test's. The working run used --rm, so nothing was left behind.

Frequently asked

What characters are allowed in a Docker container name?

The message spells it out: only [a-zA-Z0-9][a-zA-Z0-9_.-] are allowed. The first character is a letter or digit; the rest may be letters, digits, underscore, dot or hyphen.

Can a Docker container name contain a space or a slash?

No. In this test docker run --name with 'fix8-d3 web' and with fix8-d3/web both failed with 'invalid container name' and exit code 125.

How do I fix 'invalid container name' in docker run?

Replace the space or slash in the --name value with a hyphen, underscore or dot, for example fix8-d3-web, and run the command again.

More decoded errors in the Fixes category.