docker/cli · error

username is empty

Error message

username is empty

What it means

Raised by verifyLoginFlags (cli/command/registry/login.go:84) when the --username flag was explicitly set on the command line but its value is an empty string. Explicitly passing an empty username is treated as a mistake rather than a request to prompt.

Source

Thrown at cli/command/registry/login.go:84

	flags.BoolVar(&opts.passwordStdin, "password-stdin", false, "Take the Password or Personal Access Token (PAT) from stdin")

	return cmd
}

// verifyLoginFlags validates flags set on the command.
//
// TODO(thaJeztah); combine with verifyLoginOptions, but this requires rewrites of many tests.
func verifyLoginFlags(flags *pflag.FlagSet, opts loginOptions) error {
	if flags.Changed("password-stdin") || opts.password == "-" {
		if flags.Changed("password") && opts.password != "-" {
			return errors.New("conflicting options: cannot specify both --password and --password-stdin")
		}
		if !flags.Changed("username") {
			return errors.New("the --password-stdin option requires --username to be set")
		}
	}
	if flags.Changed("username") && opts.user == "" {
		return errors.New("username is empty")
	}
	if flags.Changed("password") && opts.password == "" {
		return errors.New("password is empty")
	}
	return nil
}

// readSecretFromStdin reads the secret from r and returns it as a string.
// It trims terminal line-endings (LF, CRLF, or CR), which may be added when
// inputting interactively or piping input. The value is otherwise treated as
// opaque, preserving any other whitespace, including newlines, per [NIST SP 800-63B §5.1.1.2].
// Note that trimming whitespace may still happen elsewhere (see [NIST SP 800-63B (revision 4) §3.1.1.2]);
//
// > Verifiers **MAY** make limited allowances for mistyping (e.g., removing
// > leading and trailing whitespace characters before verification, allowing
// > the verification of passwords with differing cases for the leading character)
//
// [NIST SP 800-63B §5.1.1.2]: https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver

View on GitHub (pinned to e9452d6e78)

Solutions

1. Verify the shell/CI variable actually has a value (echo its length or use ${VAR:?} to fail fast: docker login -u "${REGISTRY_USER:?}" ...)
2. If you want the interactive username prompt, omit the -u flag entirely instead of passing an empty value
3. Check CI secret scoping — org/repo/environment-level secrets can be silently empty in forks or unmatched environments

Example fix

# before (REGISTRY_USER unset)
docker login -u "$REGISTRY_USER" --password-stdin registry.example.com

# after (fail fast with a clear message if unset)
docker login -u "${REGISTRY_USER:?REGISTRY_USER is not set}" --password-stdin registry.example.com

When it happens

Trigger: docker login -u '' registry.example.com; docker login --username="" — the flag is marked Changed by pflag but opts.user is "". Typically the result of an unset shell variable: docker login -u "$USER_VAR" where USER_VAR is empty.

Common situations: CI secrets/variables that are defined but empty (misnamed variable, wrong scope, unexported env var); templating systems rendering an empty value into the -u flag; quoting bugs where the intended value lands in the next argument.

Related errors

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

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