docker/cli · error

not allowed to alias with builtin

Error message

not allowed to alias with builtin %q as target

What it means

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.

Solutions

1. Point the alias at an installed plugin name, e.g. `{"aliases": {"builder": "buildx"}}`.
2. Install the intended plugin (e.g. `docker buildx install`) so the alias target is a real plugin command.
3. Remove the alias entry if you did not intend to redirect to a plugin.

Example fix

// before — ~/.docker/config.json
{
  "aliases": { "builder": "build" }
}
$ docker build .
Error: not allowed to alias with builtin "build" as target

// after
{
  "aliases": { "builder": "buildx" }
}

// Ensure the alias target is a plugin command, not a builtin
func aliasTargetsPlugin(target string) (bool, error) {
    // run `docker <target> --help` is not authoritative; instead check known plugins
    knownPlugins := map[string]struct{}{"buildx": {}, "compose": {}, "scout": {}}
    parts := strings.Fields(target)
    if len(parts) == 0 { return false, errors.New("empty alias target") }
    _, ok := knownPlugins[parts[0]]
    return ok, nil
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• not allowed to alias
• invalid field ' ' must be a key=value pair
• invalid mode specified
• invalid field in config request
• error reading from STDIN: data is empty

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/de330e4e73320f08. Report an issue: GitHub.

Appendix: 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 4f84911bfe)