docker/cli · error

not allowed to alias with builtin %q as target

Error message

not allowed to alias with builtin %q as target

What it means

Error "not allowed to alias with builtin %q as target" thrown in docker/cli.

Source

Thrown at cmd/docker/aliases.go:33

)

var allowedAliases = map[string]struct{}{
	keyBuilderAlias: {},
}

func processAliases(dockerCli command.Cli, cmd *cobra.Command, args, osArgs []string) ([]string, []string, []string, error) {
	var err error
	var envs []string
	aliasMap := dockerCli.ConfigFile().Aliases
	aliases := make([][2][]string, 0, len(aliasMap))

	for k, v := range aliasMap {
		if _, ok := allowedAliases[k]; !ok {
			return args, osArgs, envs, fmt.Errorf("not allowed to alias %q (allowed: %#v)", k, allowedAliases)
		}
		if c, _, err := cmd.Find(strings.Split(v, " ")); err == nil {
			if !pluginmanager.IsPluginCommand(c) {
				return args, osArgs, envs, fmt.Errorf("not allowed to alias with builtin %q as target", v)
			}
		}
		aliases = append(aliases, [2][]string{{k}, {v}})
	}

	args, osArgs, envs, err = processBuilder(dockerCli, cmd, args, os.Args)
	if err != nil {
		return args, os.Args, envs, err
	}

	for _, al := range aliases {
		var didChange bool
		args, didChange = stringSliceReplaceAt(args, al[0], al[1], 0)
		if didChange {
			osArgs, _ = stringSliceReplaceAt(osArgs, al[0], al[1], -1)
			break
		}
	}

View on GitHub (pinned to e9452d6e78)

When it happens

Trigger: Thrown at cmd/docker/aliases.go:33 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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