{"record":{"id":"4edcb7bbf8eb1f27","repo":"docker/cli","slug":"not-allowed-to-alias-q-allowed-v","errorCode":null,"errorMessage":"not allowed to alias %q (allowed: %#v)","messagePattern":"not allowed to alias %q \\(allowed: %#v\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/docker/aliases.go","lineNumber":29,"sourceCode":")\n\nconst (\n\tkeyBuilderAlias = \"builder\"\n)\n\nvar allowedAliases = map[string]struct{}{\n\tkeyBuilderAlias: {},\n}\n\nfunc processAliases(dockerCli command.Cli, cmd *cobra.Command, args, osArgs []string) ([]string, []string, []string, error) {\n\tvar err error\n\tvar envs []string\n\taliasMap := dockerCli.ConfigFile().Aliases\n\taliases := make([][2][]string, 0, len(aliasMap))\n\n\tfor k, v := range aliasMap {\n\t\tif _, ok := allowedAliases[k]; !ok {\n\t\t\treturn args, osArgs, envs, fmt.Errorf(\"not allowed to alias %q (allowed: %#v)\", k, allowedAliases)\n\t\t}\n\t\tif c, _, err := cmd.Find(strings.Split(v, \" \")); err == nil {\n\t\t\tif !pluginmanager.IsPluginCommand(c) {\n\t\t\t\treturn args, osArgs, envs, fmt.Errorf(\"not allowed to alias with builtin %q as target\", v)\n\t\t\t}\n\t\t}\n\t\taliases = append(aliases, [2][]string{{k}, {v}})\n\t}\n\n\targs, osArgs, envs, err = processBuilder(dockerCli, cmd, args, os.Args)\n\tif err != nil {\n\t\treturn args, os.Args, envs, err\n\t}\n\n\tfor _, al := range aliases {\n\t\tvar didChange bool\n\t\targs, didChange = stringSliceReplaceAt(args, al[0], al[1], 0)\n\t\tif didChange {","sourceCodeStart":11,"sourceCodeEnd":47,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cmd/docker/aliases.go#L11-L47","documentation":"Returned by processAliases() when the docker CLI config (`~/.docker/config.json`) contains an `aliases` entry whose key is not in the allowedAliases map. Currently only the key \"builder\" is permitted (keyBuilderAlias). %q is the offending key, %#v prints the full allowedAliases map. Docker restricts aliases to a vetted set to prevent shadowing arbitrary commands.","triggerScenarios":"Editing `~/.docker/config.json` and adding an `aliases` object with a key other than \"builder\" (e.g. `{\"aliases\": {\"run\": \"container run\"}}`), then running any docker command — processAliases runs early in runDocker().","commonSituations":"Users hand-editing config.json expecting arbitrary alias support; stale config from an experimental build; copy-pasting config snippets from outdated guides.","solutions":["Remove or rename the unsupported alias key from `~/.docker/config.json`'s `aliases` object — keep only \"builder\".","Use a shell alias (e.g. bash `alias`) for command shortcuts outside the supported set instead of the docker config.","Validate config.json is well-formed JSON after editing."],"exampleFix":"// before — ~/.docker/config.json\n{\n  \"aliases\": { \"run\": \"container run\" }\n}\n$ docker ps\nError: not allowed to alias \"run\" (allowed: map[string]struct {}{\"builder\":struct{}{}})\n\n// after\n{\n  \"aliases\": { \"builder\": \"buildx\" }\n}","handlingStrategy":"validation","validationCode":"// Validate config.json aliases keys against the allowed set before docker runs\nvar allowedAliases = map[string]struct{}{\"builder\": {}}\n\nfunc validateAliases(cfg map[string]json.RawMessage) error {\n    raw, ok := cfg[\"aliases\"]\n    if !ok { return nil }\n    var m map[string]string\n    if err := json.Unmarshal(raw, &m); err != nil { return err }\n    for k := range m {\n        if _, ok := allowedAliases[k]; !ok {\n            return fmt.Errorf(\"alias %q not allowed\", k)\n        }\n    }\n    return nil\n}","typeGuard":"func isAllowedAliasKey(k string) bool {\n    _, ok := map[string]struct{}{\"builder\": {}}[k]\n    return ok\n}","tryCatchPattern":null,"preventionTips":["Only put 'builder' under aliases in config.json.","Use shell aliases for arbitrary command shortcuts.","Lint config.json in dotfile management (chezmoi/ansible) to catch stray keys."],"tags":["docker","config","aliases","validation"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}