{"id":"c03ca17fa2228342","repo":"docker/cli","slug":"user-agent-cannot-be-blank","errorCode":null,"errorMessage":"user agent cannot be blank","messagePattern":"user agent cannot be blank","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/cli_options.go","lineNumber":232,"sourceCode":"\t}\n\n\tif len(env) == 0 {\n\t\t// We should probably not hit this case, as we don't skip values\n\t\t// (only return errors), but we don't want to discard existing\n\t\t// headers with an empty set.\n\t\treturn nil, nil\n\t}\n\n\t// TODO(thaJeztah): add a client.WithExtraHTTPHeaders() function to allow these headers to be _added_ to existing ones, instead of _replacing_\n\t//  see https://github.com/docker/cli/pull/5098#issuecomment-2147403871  (when updating, also update the WARNING in the function and env-var GoDoc)\n\treturn client.WithHTTPHeaders(env), nil\n}\n\n// WithUserAgent configures the User-Agent string for cli HTTP requests.\nfunc WithUserAgent(userAgent string) CLIOption {\n\treturn func(cli *DockerCli) error {\n\t\tif userAgent == \"\" {\n\t\t\treturn errors.New(\"user agent cannot be blank\")\n\t\t}\n\t\tcli.clientOpts = append(cli.clientOpts, client.WithUserAgent(userAgent))\n\t\treturn nil\n\t}\n}\n","sourceCodeStart":214,"sourceCodeEnd":238,"githubUrl":"https://github.com/docker/cli/blob/e9452d6e785f6e365712b9d71bd7517591773c86/cli/command/cli_options.go#L214-L238","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass a non-empty user-agent string to command.WithUserAgent, e.g. \"myapp/1.2.3\".","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).","Guard the call site: only append WithUserAgent when the configured value is non-empty, and fail configuration loading if it is required but blank."],"exampleFix":"// before\ncli, err := command.NewDockerCli(command.WithUserAgent(cfg.UserAgent)) // cfg.UserAgent == \"\"\n// after\nopts := []command.CLIOption{}\nif cfg.UserAgent != \"\" {\n    opts = append(opts, command.WithUserAgent(cfg.UserAgent))\n}\ncli, err := command.NewDockerCli(opts...)","handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":["docker-cli","library-embedding","http-headers","configuration"],"analyzedSha":"e9452d6e785f6e365712b9d71bd7517591773c86","analyzedAt":"2026-08-01T07:09:22.474Z","schemaVersion":2}