larksuite/cli · error

unknown flag: --{name}

Error message

unknown flag: --{name}

What it means

gatedFlagValue.Set returns this plain error when a feature-gated flag is set while its gate is closed. It is deliberately an intermediate parse error, not a final envelope: pflag wraps it and the root FlagErrorFunc (flagDidYouMean) converts it into the typed unknown-flag validation error shown to the user. The message names the gated flag as '--{name}'.

Source

Thrown at cmd/flag_gate.go:97

}

// gatedFlagValue rejects at parse time, before cobra's help/version fast
// paths (which never reach PersistentPreRunE). Its Set error carries
// cobra's own unknown-flag wording so the root FlagErrorFunc classifies it
// as an ordinary unknown flag without exposing policy state. Cobra may add
// different parse context on root/group paths than on leaf commands.
type gatedFlagValue struct {
	name  string
	inner pflag.Value
}

func (g *gatedFlagValue) String() string { return g.inner.String() }
func (g *gatedFlagValue) Type() string   { return g.inner.Type() }
func (g *gatedFlagValue) Set(string) error {
	// Intermediate parse error, not a final envelope: pflag wraps it and
	// the root FlagErrorFunc (flagDidYouMean) converts it to the typed
	// unknown-flag validation error.
	return errors.New("unknown flag: --" + g.name) //nolint:forbidigo // intermediate parse error; flagDidYouMean emits the typed envelope
}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Remove the gated flag from the command line and run the command without it.
2. Check `lark <cmd> --help` to see which flags are actually available in your build.
3. Upgrade (or downgrade) the CLI to the version where the flag is generally available.
4. If you own the feature gate, enable it via the intended config/build mechanism before using the flag.

Example fix

// before
lark foo --experimental-opt x   # gated flag, gate closed
// after
lark foo                        # run without the gated flag

// Go: check help output for the flag before using it
out, err := exec.Command("lark", cmd, "--help").Output()
if err != nil || !strings.Contains(string(out), "--"+flagName) {
	return fmt.Errorf("flag --%s not available in this build", flagName)
}

func flagAvailable(helpText, flag string) bool {
	return strings.Contains(helpText, "--"+flag)
}

// Go: treat the surfaced unknown-flag validation error as a gate signal
if err := cmd.Run(); err != nil {
	var verr *errs.ValidationError
	if errors.As(err, &verr) && strings.Contains(verr.Error(), "unknown flag") {
		// drop the gated flag and retry without it
	}
	return err
}

When it happens

Trigger: Using a command flag that is registered but feature-gated off (e.g. an experimental flag not enabled in the current build/config); any Cobra/pflag parse that invokes Set on the gated flag value.

Common situations: Following docs or scripts for a feature not yet enabled in your CLI version; copy-pasted command lines from newer/older releases; CI running a build without the feature gate enabled.

Related errors

• invalid --param format
• unsafe --output-dir
• command set %d command %d: command path %q conflicts with %s
• command set %d command %d (%s): %w
• profile name cannot be empty

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