{"record":{"id":"973e8ce9b2873180","repo":"langgenius/dify","slug":"unknown-flag-name","errorCode":null,"errorMessage":"unknown flag: --${name}","messagePattern":"unknown flag: --(.+?)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"cli/src/framework/flags.ts","lineNumber":150,"sourceCode":"function validateFlagOptions(name: string, raw: string, def: FlagDefinition): void {\n  if (def.options !== undefined && !def.options.includes(raw))\n    throw new UnsupportedArgValueError(name, def, raw)\n}\n\ntype ResolvedFlag = {\n  name: string\n  def: FlagDefinition\n  label: string\n  inlineRaw: string | undefined\n}\n\nfunction resolveToken(token: string, flags: Record<string, FlagDefinition>): ResolvedFlag | null {\n  if (token.startsWith('--')) {\n    const eqIdx = token.indexOf('=')\n    const name = eqIdx !== -1 ? token.slice(2, eqIdx) : token.slice(2)\n    const inlineRaw = eqIdx !== -1 ? token.slice(eqIdx + 1) : undefined\n    const def = flags[name]\n    if (!def) throw new Error(`unknown flag: --${name}`)\n    return { name, def, label: `--${name}`, inlineRaw }\n  }\n\n  if (token.length === 2 && token[1] !== undefined) {\n    const char = token[1]\n    const resolved = resolveByChar(char, flags)\n    if (!resolved) throw new Error(`unknown flag: -${char}`)\n    const [name, def] = resolved\n    return { name, def, label: `-${char}`, inlineRaw: undefined }\n  }\n\n  return null\n}\n\n// Scans argv for a boolean flag without throwing on unknown tokens, so it is safe\n// to call before the command-specific flag set is known (e.g. global flags).\nexport function hasBooleanFlag(argv: readonly string[], name: string, char?: string): boolean {\n  for (const token of argv) {","sourceCodeStart":132,"sourceCodeEnd":168,"githubUrl":"https://github.com/langgenius/dify/blob/ef8544b173fd6cd7a8e71df2cab576e52bebbfbc/cli/src/framework/flags.ts#L132-L168","documentation":"A bare Error from resolveToken (flags.ts:150) when a `--name` token has no matching entry in the merged flag set (command flags + GLOBAL_FLAGS like --verbose). parseArgv merges GLOBAL_FLAGS so --verbose/-v are always known; anything else unknown throws. Plain Error, so exit-code routing is lost (becomes generic 1, not Usage 2).","triggerScenarios":"Typing a flag the command doesn't define: `--json` instead of `-o json`, `--output` instead of `--out`, `--workspace` for a command that takes a positional. Also using a flag from a different difyctl subcommand, or a removed/renamed flag after upgrade.","commonSituations":"Renamed flags between versions; habit from another tool (kubectl, gh, aws cli); autocomplete suggesting the wrong name; copy-paste from outdated docs.","solutions":["Run `difyctl <cmd> --help` and copy the exact flag name.","For output format, remember the short form is `-o` not `--output` (defined in outputFormatFlag, flags.ts:38-48).","If you expected the flag to exist, check the installed version (`difyctl --version`) and upgrade.","If maintaining difyctl: wrap resolveToken failures in BaseError(UsageInvalidFlag) so the exit is 2 and the message is consistent."],"exampleFix":"// before\ndifyctl apps list --json\n\n// after\ndifyctl apps list -o json","handlingStrategy":"validation","validationCode":"// before constructing argv, filter through the command's known long flags\nconst KNOWN_LONG = new Set(['--host', '--insecure', '--verbose', '--output'])\nfunction checkLongFlags(argv: string[]): void {\n  for (const t of argv) {\n    if (t.startsWith('--')) {\n      const name = t.split('=')[0]!\n      if (!KNOWN_LONG.has(name)) throw new Error(`unknown flag ${name}`)\n    }\n  }\n}","typeGuard":"function isKnownLongFlag(token: string, known: ReadonlySet<string>): boolean {\n  if (!token.startsWith('--')) return true\n  return known.has(token.split('=')[0]!)\n}","tryCatchPattern":null,"preventionTips":["Keep a single source of truth for the flags your script uses; derive it from --help.","Prefer long flags over short to make typos obvious.","After upgrading difyctl, re-read --help — flags get renamed."],"tags":["cli","flags","unknown-flag","usage"],"backgroundTag":null,"analyzedSha":"ef8544b173fd6cd7a8e71df2cab576e52bebbfbc","analyzedAt":"2026-08-12T05:15:17.394Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}