docker/cli · error

not allowed to alias

Error message

not allowed to alias %q (allowed: %#v)

What it means

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.

Solutions

1. Remove or rename the unsupported alias key from `~/.docker/config.json`'s `aliases` object — keep only "builder".
2. Use a shell alias (e.g. bash `alias`) for command shortcuts outside the supported set instead of the docker config.
3. Validate config.json is well-formed JSON after editing.

Example fix

// before — ~/.docker/config.json
{
  "aliases": { "run": "container run" }
}
$ docker ps
Error: not allowed to alias "run" (allowed: map[string]struct {}{"builder":struct{}{}})

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

// Validate config.json aliases keys against the allowed set before docker runs
var allowedAliases = map[string]struct{}{"builder": {}}

func validateAliases(cfg map[string]json.RawMessage) error {
    raw, ok := cfg["aliases"]
    if !ok { return nil }
    var m map[string]string
    if err := json.Unmarshal(raw, &m); err != nil { return err }
    for k := range m {
        if _, ok := allowedAliases[k]; !ok {
            return fmt.Errorf("alias %q not allowed", k)
        }
    }
    return nil
}

func isAllowedAliasKey(k string) bool {
    _, ok := map[string]struct{}{"builder": {}}[k]
    return ok
}

When it happens

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

Common situations: Users hand-editing config.json expecting arbitrary alias support; stale config from an experimental build; copy-pasting config snippets from outdated guides.

Related errors

• not allowed to alias with builtin
• 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/4edcb7bbf8eb1f27. Report an issue: GitHub.

Appendix: source

Thrown at cmd/docker/aliases.go:29

)

const (
	keyBuilderAlias = "builder"
)

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 {

View on GitHub (pinned to 4f84911bfe)