{"record":{"id":"9c9625e822cd90ea","repo":"docker/cli","slug":"key-name-s-must-start-with-lowercase-alphanumer-9c9625","errorCode":null,"errorMessage":"key name \"%s\" must start with lowercase alphanumeric characters and can include \"-\" or \"_\" after the first character","messagePattern":"key name \"(.+?)\" must start with lowercase alphanumeric characters and can include \"-\" or \"_\" after the first character","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/docker-trust/trust/key_load.go","lineNumber":49,"sourceCode":"\tvar options keyLoadOptions\n\tcmd := &cobra.Command{\n\t\tUse:   \"load [OPTIONS] KEYFILE\",\n\t\tShort: \"Load a private key file for signing\",\n\t\tArgs:  cli.ExactArgs(1),\n\t\tRunE: func(cmd *cobra.Command, args []string) error {\n\t\t\treturn loadPrivKey(dockerCLI, args[0], options)\n\t\t},\n\t\tDisableFlagsInUseLine: true,\n\t}\n\tflags := cmd.Flags()\n\tflags.StringVar(&options.keyName, \"name\", \"signer\", \"Name for the loaded key\")\n\treturn cmd\n}\n\nfunc loadPrivKey(streams command.Streams, keyPath string, options keyLoadOptions) error {\n\t// validate the key name if provided\n\tif options.keyName != \"\" && !validKeyName(options.keyName) {\n\t\treturn fmt.Errorf(\"key name \\\"%s\\\" must start with lowercase alphanumeric characters and can include \\\"-\\\" or \\\"_\\\" after the first character\", options.keyName)\n\t}\n\ttrustDir := trust.GetTrustDirectory()\n\tkeyFileStore, err := storage.NewPrivateKeyFileStorage(trustDir, notary.KeyExtension)\n\tif err != nil {\n\t\treturn err\n\t}\n\tprivKeyImporters := []trustmanager.Importer{keyFileStore}\n\n\t_, _ = fmt.Fprintf(streams.Out(), \"Loading key from \\\"%s\\\"...\\n\", keyPath)\n\n\t// Always use a fresh passphrase retriever for each import\n\tpassRet := trust.GetPassphraseRetriever(streams.In(), streams.Out())\n\tkeyBytes, err := getPrivKeyBytesFromPath(keyPath)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"refusing to load key from %s: %w\", keyPath, err)\n\t}\n\tif err := loadPrivKeyBytesToStore(keyBytes, privKeyImporters, keyPath, options.keyName, passRet); err != nil {\n\t\treturn fmt.Errorf(\"error importing key from %s: %w\", keyPath, err)","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cmd/docker-trust/trust/key_load.go#L31-L67","documentation":"In loadPrivKey (key_load.go:46-50), the --name flag value fails the validKeyName regex (same ^[a-z0-9][a-z0-9_\\-]*$ pattern shared with key_generate). The default --name is 'signer' (key_load.go:42), so this only fires when the user explicitly passes a non-conformant --name.","triggerScenarios":"Running 'docker trust key load <keyfile> --name <NAME>' where NAME contains uppercase, spaces, dots, leading hyphen/underscore, '@', or other punctuation, or is empty after the flag.","commonSituations":"User passes a display name like 'Frontend Team' or 'CI'; uses an email 'ci@corp'; copies a role name with uppercase; passes '--name=' (empty).","solutions":["Use a conformant --name: lowercase alphanumerics with optional '-'/'_', e.g. --name frontend-team.","Omit --name to use the default 'signer'.","Strip/normalize the value to lowercase and replace disallowed chars with '-' or '_'."],"exampleFix":"# before\ndocker trust key load priv.key --name 'CI Signer'\n# after\ndocker trust key load priv.key --name ci-signer","handlingStrategy":"validation","validationCode":"// Reuse the shared regex to validate --name before loading.\nfunc validateLoadKeyName(name string) error {\n    if name != \"\" && !validKeyName(name) {\n        return fmt.Errorf(\"key name %q must start with lowercase alphanumeric and may contain '-' or '_'\", name)\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"if options.keyName != \"\" && !validKeyName(options.keyName) {\n    return fmt.Errorf(\"key name %q must start with lowercase alphanumeric ...\", options.keyName)\n}","preventionTips":["Use kebab-case lowercase names for --name.","Omit --name to default to 'signer' when the role name does not matter.","Validate names in automation scripts before invoking the command."],"tags":["docker","notary","content-trust","validation","key-naming","input-validation"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}