What causes "name %q must not contain whitespace" in larksuite/cli?

Run strings.TrimSpace (and strip internal whitespace) on the name before constructing the Spec.

name %q must not contain whitespace

Error message

name %q must not contain whitespace

What it means

validateAliasName enforces that alias names contain no whitespace characters (space, tab, CR, LF). Flag tokens on a command line can never contain whitespace without quoting, so a whitespace-containing alias would be unreachable and likely indicates a parsing or construction bug upstream. Bind rejects such specs at registration time rather than letting a dead alias silently ship.

Source

Thrown at internal/flagalias/flagalias.go:278

		return value.trackedValue
	}
	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 {

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Run strings.TrimSpace (and strip internal whitespace) on the name before constructing the Spec.
If the name should be two flags, split it into separate Specs instead of one whitespace-containing name.
Replace internal spaces with a valid separator such as '-' (e.g. "json-output").
If reading names from files, open with normalization for CRLF (strings.TrimRight(line, "\r\n")) before use.

Example fix

// before
name := line // e.g. "json output\r"
specs = append(specs, flagalias.Spec{Name: name, Target: target})
// after
name := strings.TrimSpace(strings.ReplaceAll(line, " ", "-"))
specs = append(specs, flagalias.Spec{Name: name, Target: target})

Defensive patterns

Strategy: validation

Validate before calling

func normalizeSpecName(raw string) string {
	return strings.TrimSpace(strings.Join(strings.Fields(raw), "-"))
}
// before Bind:
if strings.ContainsAny(name, " \t\r\n") {
	return fmt.Errorf("alias name %q contains whitespace", name)
}

Type guard

func hasNoWhitespace(s string) bool {
	return !strings.ContainsAny(s, " \t\r\n")
}

Prevention

TrimSpace every name read from files, env vars, or CLI input before use.
Normalize CRLF (\r\n) when parsing line-based config files.
Prefer '-' as the internal word separator for multi-word flag names.

When it happens

Trigger: Calling flagalias.Bind with a Spec whose name contains a space, tab, or newline — e.g. Name: "json output", a name joined from a list with strings.Join(parts, " "), or a name read from a config file/line that still carries a trailing "\r" (Windows CRLF) or "\n".

Common situations: Names parsed from CSV or env files without TrimSpace; a CRLF left over from a Windows-edited config; templated flag names where a placeholder expanded to multiple words.

Related errors

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