docker/cli · error

user agent cannot be blank

Error message

user agent cannot be blank

What it means

Returned by the WithUserAgent CLIOption in cli/command/cli_options.go when it is constructed with an empty string. The option exists so embedders of the docker CLI library can brand their HTTP User-Agent; an empty value would silently strip identification from API requests, so the option fails fast instead of accepting it.

Source

Thrown at cli/command/cli_options.go:232

	}

	if len(env) == 0 {
		// We should probably not hit this case, as we don't skip values
		// (only return errors), but we don't want to discard existing
		// headers with an empty set.
		return nil, nil
	}

	// TODO(thaJeztah): add a client.WithExtraHTTPHeaders() function to allow these headers to be _added_ to existing ones, instead of _replacing_
	//  see https://github.com/docker/cli/pull/5098#issuecomment-2147403871  (when updating, also update the WARNING in the function and env-var GoDoc)
	return client.WithHTTPHeaders(env), nil
}

// WithUserAgent configures the User-Agent string for cli HTTP requests.
func WithUserAgent(userAgent string) CLIOption {
	return func(cli *DockerCli) error {
		if userAgent == "" {
			return errors.New("user agent cannot be blank")
		}
		cli.clientOpts = append(cli.clientOpts, client.WithUserAgent(userAgent))
		return nil
	}
}

View on GitHub (pinned to e9452d6e78)

Solutions

1. Pass a non-empty user-agent string to command.WithUserAgent, e.g. "myapp/1.2.3".
2. If you don't need a custom user agent, omit the WithUserAgent option entirely — the CLI falls back to its default Docker-Client UA (see UserAgent() in cli/command/cli.go).
3. Guard the call site: only append WithUserAgent when the configured value is non-empty, and fail configuration loading if it is required but blank.

Example fix

// before
cli, err := command.NewDockerCli(command.WithUserAgent(cfg.UserAgent)) // cfg.UserAgent == ""
// after
opts := []command.CLIOption{}
if cfg.UserAgent != "" {
    opts = append(opts, command.WithUserAgent(cfg.UserAgent))
}
cli, err := command.NewDockerCli(opts...)

When it happens

Trigger: Calling command.WithUserAgent("") when building a DockerCli via NewDockerCli/Initialize — typically because the user-agent string comes from an unset variable, empty config field, or blank environment value.

Common situations: Go programs embedding docker/cli as a library that read the user agent from a config file or env var that is empty in some environments; refactors that moved the UA constant and left a zero-value string; tests constructing a CLI with default-initialized option structs.

Related errors

• conflicting options: cannot specify both --host and --contex
• docker endpoint configuration is required
• no context specified
• unrecognized config key:
• no unlock key is set

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