docker/cli · error

error: username is required

Error message

error: username is required

What it means

Raised by PromptUserForCredentials in the Docker CLI (cli/command/registry.go:148) when, after interactively prompting for a username, both the user's input and the default username (from previously stored credentials) are empty. A registry login cannot proceed without an identity, so the CLI aborts rather than sending an anonymous auth request.

Source

Thrown at cli/command/registry.go:148

		var msg string
		defaultUsername = strings.TrimSpace(defaultUsername)
		if defaultUsername == "" {
			msg = "Username: "
		} else {
			msg = fmt.Sprintf("Username (%s): ", defaultUsername)
		}

		var err error
		argUser, err = prompt.ReadInput(ctx, stdIn, cli.Out(), msg)
		if err != nil {
			return registrytypes.AuthConfig{}, err
		}
		if argUser == "" {
			argUser = defaultUsername
		}
		if argUser == "" {
			return registrytypes.AuthConfig{}, errors.New("error: username is required")
		}
	}

	isEmpty := strings.TrimSpace(argPassword) == ""
	if isEmpty {
		restoreInput, err := prompt.DisableInputEcho(stdIn)
		if err != nil {
			return registrytypes.AuthConfig{}, err
		}
		defer func() {
			if err := restoreInput(); err != nil {
				// TODO(thaJeztah): we should consider printing instructions how
				//  to restore this manually (other than restarting the shell).
				//  e.g., 'run stty echo' when in a Linux or macOS shell, but
				//  PowerShell and CMD.exe may need different instructions.
				_, _ = fmt.Fprintln(cli.Err(), "Error: failed to restore terminal state to echo input:", err)
			}
		}()

View on GitHub (pinned to e9452d6e78)

Solutions

1. Type a non-empty username at the prompt, or pass it explicitly: docker login -u <username> <registry>
2. In scripts, always supply --username and use --password-stdin instead of relying on interactive prompts
3. For Docker Hub, consider a Personal Access Token with your Hub username (create at https://app.docker.com/settings)

Example fix

# before (prompt answered with empty input)
docker login registry.example.com
# Username: <enter>
# error: username is required

# after
echo "$REGISTRY_TOKEN" | docker login registry.example.com -u myuser --password-stdin

When it happens

Trigger: Running `docker login` (or any command that triggers credential prompting, e.g. `docker pull` against a private registry) where no --username flag was given, the interactive Username prompt is answered with an empty line, and no default username exists in the credential store for that registry.

Common situations: First-time login to a registry where the user just presses Enter at the Username prompt expecting a default; scripts piping empty input into `docker login`; fresh machines or CI runners with no ~/.docker/config.json entry for the registry so no default username can be offered.

Related errors

• error: password is required
• conflicting options: cannot specify both --password and --pa
• the --password-stdin option requires --username to be set
• username is empty
• password is empty

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/f0d2936cc1539533.json. Report an issue: GitHub.