{"record":{"id":"de330e4e73320f08","repo":"docker/cli","slug":"not-allowed-to-alias-with-builtin-q-as-target","errorCode":null,"errorMessage":"not allowed to alias with builtin %q as target","messagePattern":"not allowed to alias with builtin %q as target","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/docker/aliases.go","lineNumber":33,"sourceCode":")\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 {\n\t\t\tosArgs, _ = stringSliceReplaceAt(osArgs, al[0], al[1], -1)\n\t\t\tbreak\n\t\t}\n\t}","sourceCodeStart":15,"sourceCodeEnd":51,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cmd/docker/aliases.go#L15-L51","documentation":"Returned by processAliases() when an allowed alias key (e.g. \"builder\") is mapped to a value that resolves to a *builtin* docker command rather than a plugin. Docker only permits aliasing to external plugin commands (pluginmanager.IsPluginCommand check). %q is the disallowed builtin target value. This prevents aliases from overriding built-in commands.","triggerScenarios":"Setting `{\"aliases\": {\"builder\": \"build\"}}` in config.json where \"build\" resolves to docker's built-in build command (or any non-plugin command), then running docker.","commonSituations":"Misunderstanding that the builder alias is meant to point at a plugin (like buildx), not a core command; pointing the alias at a command name that happens to be builtin.","solutions":["Point the alias at an installed plugin name, e.g. `{\"aliases\": {\"builder\": \"buildx\"}}`.","Install the intended plugin (e.g. `docker buildx install`) so the alias target is a real plugin command.","Remove the alias entry if you did not intend to redirect to a plugin."],"exampleFix":"// before — ~/.docker/config.json\n{\n  \"aliases\": { \"builder\": \"build\" }\n}\n$ docker build .\nError: not allowed to alias with builtin \"build\" as target\n\n// after\n{\n  \"aliases\": { \"builder\": \"buildx\" }\n}","handlingStrategy":"validation","validationCode":"// Ensure the alias target is a plugin command, not a builtin\nfunc aliasTargetsPlugin(target string) (bool, error) {\n    // run `docker <target> --help` is not authoritative; instead check known plugins\n    knownPlugins := map[string]struct{}{\"buildx\": {}, \"compose\": {}, \"scout\": {}}\n    parts := strings.Fields(target)\n    if len(parts) == 0 { return false, errors.New(\"empty alias target\") }\n    _, ok := knownPlugins[parts[0]]\n    return ok, nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Point the 'builder' alias only at installed plugins like buildx.","Install the target plugin before configuring the alias.","Never alias to a builtin command name."],"tags":["docker","config","aliases","plugins","validation"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}