docker/cli · error

error: username is required

Error message

error: username is required

What it means

Thrown by PromptUserForCredentials after the interactive username prompt returns an empty string and no default username is available. The login flow cannot proceed without a username.

Solutions

1. Type your Docker ID (or email) at the prompt and press Enter.
2. Pass the username explicitly: 'docker login -u <user>'.
3. Use a Personal Access Token (PAT) with --password-stdin for non-interactive flows.

Example fix

# before (pressing Enter at Username: prompt)
docker login
# after
docker login -u myuser

// Ensure a username is available before prompting
if strings.TrimSpace(username) == "" && strings.TrimSpace(defaultUsername) == "" {
    return fmt.Errorf("a username is required; pass -u or set a default")
}

When it happens

Trigger: Interactive 'docker login' where the user presses Enter at the 'Username:' prompt without typing anything and there is no stored/default username (registry.go lines 144-148).

Common situations: Accidental Enter at the prompt; empty DOCKER_USER env; first-time login on a fresh install.

Related errors

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

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/f0d2936cc1539533. Report an issue: GitHub.

Appendix: 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 4f84911bfe)