larksuite/cli · error

name %q must not contain '='

Error message

name %q must not contain '='

What it means

validateAliasName rejects names containing '=' because '=' is the flag=value assignment token in pflag/cobra syntax. An alias name with '=' would collide with value-assignment parsing and could never be resolved as a plain flag name, so Bind fails fast at registration. This typically means an "NAME=VALUE" style string was passed where only the NAME belongs.

Source

Thrown at internal/flagalias/flagalias.go:280

	tracked := &trackedValue{Value: flag.Value, canonical: flag.Name}
	if slice, ok := flag.Value.(pflag.SliceValue); ok {
		flag.Value = &trackedSliceValue{trackedValue: tracked, slice: slice}
	} else {
		flag.Value = tracked
	}
	return tracked
}

func validateAliasName(name string) error {
	switch {
	case name == "":
		return fmt.Errorf("name must not be empty")
	case strings.HasPrefix(name, "-"):
		return fmt.Errorf("name %q must not include leading dashes", name)
	case strings.ContainsAny(name, " \t\r\n"):
		return fmt.Errorf("name %q must not contain whitespace", name)
	case strings.Contains(name, "="):
		return fmt.Errorf("name %q must not contain '='", name)
	default:
		return nil
	}
}

func collectRegistered(dst map[string]string, set *pflag.FlagSet) {
	if set == nil {
		return
	}
	set.VisitAll(func(flag *pflag.Flag) {
		dst[flag.Name] = flag.Name
	})
}

func collectAnnotatedAliases(dst map[string]string, set *pflag.FlagSet, normalize func(string) string) {
	if set == nil {
		return
	}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Split the string on '=' and use only the left side as the Spec name (strings.Cut(s, "=")).
2. If the intent is a default value, set it via the flag's default-value mechanism, not the alias name.
3. Reject or warn on key=value entries at config load so malformed entries never reach Bind.
4. Remember defaults may legitimately contain '='; only the NAME side must be '='-free.

Example fix

// before
name := entry // e.g. "output=json"
specs = append(specs, flagalias.Spec{Name: name, Target: target})
// after
name, _, _ := strings.Cut(entry, "=")
specs = append(specs, flagalias.Spec{Name: name, Target: target})

// split KEY=VALUE input before building specs:
name, value, hasValue := strings.Cut(entry, "=")
if hasValue {
	// use value as a default, never part of the name
}
if strings.Contains(name, "=") {
	return fmt.Errorf("alias name %q contains '='", name)
}

func isCleanFlagToken(s string) bool {
	return s != "" && !strings.ContainsAny(s, "= \t\r\n") && !strings.HasPrefix(s, "-")
}

When it happens

Trigger: Calling flagalias.Bind with a Spec name derived from an env-var-style or key=value string, e.g. Name: "output=json", or splitting a config entry on the wrong delimiter so the value stays attached to the name.

Common situations: Parsing a .env or properties file and passing whole lines as names; users writing "--flag=value" into a custom-alias config field; joining name and default value into one string before building the Spec.

Related errors

• name %q must not include leading dashes
• name %q must not contain whitespace
• name must not be empty
• Multiple sheets matched; pass --sheet-id or --sheet-name
• invalid --param format

AI-assisted analysis of larksuite/cli@7fd6ef3c07 (2026-09-04). Data as JSON: /api/errors/61a0c4170b0bb11b. Report an issue: GitHub.