docker/cli · error

signer name " " must start with lowercase alphanumeric…

Error message

signer name "%s" must start with lowercase alphanumeric characters and can include "-" or "_" after the first character

What it means

Returned by `docker trust signer add` (addSigner) when the signer NAME argument fails the validSignerName regex `^[a-z0-9][a-z0-9\_\-]*$`. The name must start with a lowercase letter or digit and may contain lowercase alphanumerics, underscores, or hyphens thereafter. Uppercase, leading underscore/hyphen, or other characters are rejected because the name becomes a TUF delegation role (targets/<name>).

Solutions

1. Use a lowercase-alphanumeric-first name, e.g. 'alice', 'ci-bot', 'team_a'.
2. Strip or transform uppercase and leading special characters before passing the name.
3. Note 'releases' is also reserved (separate check at signer_add.go:55) — choose a different name.

Example fix

// before
$ docker trust signer add Alice registry.example.com/app --key alice.pub
Error: signer name "Alice" must start with lowercase alphanumeric...

// after
$ docker trust signer add alice registry.example.com/app --key alice.pub

// Mirror the CLI's regex before invoking signer add
import "regexp"

var validSignerName = regexp.MustCompile(`^[a-z0-9][a-z0-9\_\-]*$`).MatchString

func validateSignerName(name string) error {
    if !validSignerName(name) {
        return fmt.Errorf("invalid signer name %q", name)
    }
    if name == "releases" { return errors.New("releases is reserved") }
    return nil
}

func isValidSignerName(name string) bool {
    matched, _ := regexp.MatchString(`^[a-z0-9][a-z0-9\_\-]*$`, name)
    return matched && name != "releases"
}

When it happens

Trigger: Running `docker trust signer add <NAME> ...` where NAME is e.g. 'Alice', '-dev', '_ci', 'Dev_Team', or contains dots/spaces. Validated before any network call.

Common situations: Using a human name or team name with capitals; using a leading hyphen that the shell may also misinterpret; migrating from a system whose identifiers allow a wider character set.

Related errors

• invalid device cgroup format
• no tag specified for
• unable to read public key from file
• no signer for repository
• other flags may not be combined with --rollback

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

Appendix: source

Thrown at cmd/docker-trust/trust/signer_add.go:53

		RunE: func(cmd *cobra.Command, args []string) error {
			options.signer = args[0]
			options.repos = args[1:]
			return addSigner(cmd.Context(), dockerCLI, options)
		},
		DisableFlagsInUseLine: true,
	}
	flags := cmd.Flags()
	options.keys = opts.NewListOpts(nil)
	flags.Var(&options.keys, "key", "Path to the signer's public key file")
	return cmd
}

var validSignerName = lazyregexp.New(`^[a-z0-9][a-z0-9\_\-]*$`).MatchString

func addSigner(ctx context.Context, dockerCLI command.Cli, options signerAddOptions) error {
	signerName := options.signer
	if !validSignerName(signerName) {
		return fmt.Errorf("signer name \"%s\" must start with lowercase alphanumeric characters and can include \"-\" or \"_\" after the first character", signerName)
	}
	if signerName == "releases" {
		return errors.New("releases is a reserved keyword, use a different signer name")
	}

	if options.keys.Len() == 0 {
		return errors.New("path to a public key must be provided using the `--key` flag")
	}
	signerPubKeys, err := ingestPublicKeys(options.keys.GetSlice())
	if err != nil {
		return err
	}
	var errRepos []string
	for _, repoName := range options.repos {
		_, _ = fmt.Fprintf(dockerCLI.Out(), "Adding signer \"%s\" to %s...\n", signerName, repoName)
		if err := addSignerToRepo(ctx, dockerCLI, signerName, repoName, signerPubKeys); err != nil {
			_, _ = fmt.Fprintln(dockerCLI.Err(), err.Error()+"\n")
			errRepos = append(errRepos, repoName)

View on GitHub (pinned to 4f84911bfe)