{"record":{"id":"44e48605530c1c21","repo":"larksuite/cli","slug":"unknown-flag-name","errorCode":null,"errorMessage":"unknown flag: --{name}","messagePattern":"unknown flag: --(.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/flag_gate.go","lineNumber":97,"sourceCode":"}\n\n// gatedFlagValue rejects at parse time, before cobra's help/version fast\n// paths (which never reach PersistentPreRunE). Its Set error carries\n// cobra's own unknown-flag wording so the root FlagErrorFunc classifies it\n// as an ordinary unknown flag without exposing policy state. Cobra may add\n// different parse context on root/group paths than on leaf commands.\ntype gatedFlagValue struct {\n\tname  string\n\tinner pflag.Value\n}\n\nfunc (g *gatedFlagValue) String() string { return g.inner.String() }\nfunc (g *gatedFlagValue) Type() string   { return g.inner.Type() }\nfunc (g *gatedFlagValue) Set(string) error {\n\t// Intermediate parse error, not a final envelope: pflag wraps it and\n\t// the root FlagErrorFunc (flagDidYouMean) converts it to the typed\n\t// unknown-flag validation error.\n\treturn errors.New(\"unknown flag: --\" + g.name) //nolint:forbidigo // intermediate parse error; flagDidYouMean emits the typed envelope\n}\n","sourceCodeStart":79,"sourceCodeEnd":99,"githubUrl":"https://github.com/larksuite/cli/blob/7fd6ef3c07182257ce776cdc5a614e122d5bd4b3/cmd/flag_gate.go#L79-L99","documentation":"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}'.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove the gated flag from the command line and run the command without it.","Check `lark <cmd> --help` to see which flags are actually available in your build.","Upgrade (or downgrade) the CLI to the version where the flag is generally available.","If you own the feature gate, enable it via the intended config/build mechanism before using the flag."],"exampleFix":"// before\nlark foo --experimental-opt x   # gated flag, gate closed\n// after\nlark foo                        # run without the gated flag","handlingStrategy":"try-catch","validationCode":"// Go: check help output for the flag before using it\nout, err := exec.Command(\"lark\", cmd, \"--help\").Output()\nif err != nil || !strings.Contains(string(out), \"--\"+flagName) {\n\treturn fmt.Errorf(\"flag --%s not available in this build\", flagName)\n}","typeGuard":"func flagAvailable(helpText, flag string) bool {\n\treturn strings.Contains(helpText, \"--\"+flag)\n}","tryCatchPattern":"// Go: treat the surfaced unknown-flag validation error as a gate signal\nif err := cmd.Run(); err != nil {\n\tvar verr *errs.ValidationError\n\tif errors.As(err, &verr) && strings.Contains(verr.Error(), \"unknown flag\") {\n\t\t// drop the gated flag and retry without it\n\t}\n\treturn err\n}","preventionTips":["Consult `--help`/`schema` output for available flags per build.","Pin the CLI version in scripts so gated flags match documented behavior.","Strip experimental flags from generated command lines unless the gate is enabled."],"tags":["go","cobra","cli","feature-gate"],"backgroundTag":"unknown-flag","analyzedSha":"7fd6ef3c07182257ce776cdc5a614e122d5bd4b3","analyzedAt":"2026-09-04T21:17:44.649Z","contentChangedAt":"2026-09-04T21:17:44.649Z","schemaVersion":2},"datasetVersion":"2026-09-12T02:17:10.037Z"}