{"record":{"id":"10a07b79660c6406","repo":"langgenius/dify","slug":"unsupported-argument-value","errorCode":null,"errorMessage":"unsupported argument value","messagePattern":"unsupported argument value","errorType":"exception","errorClass":"UnsupportedArgValueError","httpStatus":null,"severity":"error","filePath":"cli/src/framework/flags.ts","lineNumber":134,"sourceCode":"  } else {\n    flags[name] = value\n  }\n}\n\nfunction resolveByChar(\n  char: string,\n  flags: Record<string, FlagDefinition>,\n): [name: string, def: FlagDefinition] | undefined {\n  for (const [name, def] of Object.entries(flags)) {\n    if (def.char === char) return [name, def]\n  }\n\n  return undefined\n}\n\nfunction 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  }","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/langgenius/dify/blob/ef8544b173fd6cd7a8e71df2cab576e52bebbfbc/cli/src/framework/flags.ts#L116-L152","documentation":"UnsupportedArgValueError thrown by validateFlagOptions (flags.ts:134) when a flag defines an `options` array (an enum) and the supplied raw value is not a member. Unlike 42/43 this IS a BaseError (IllegalArgumentError → exit 2) and the message is richer: 'illegal value <given> for flag <label>' with a hint listing supported values. The flag label includes the short form if char is set.","triggerScenarios":"Any flag built with Flags.string({ options: [...] }) or Flags.outputFormat(...) where the value falls outside the declared set. The output-format flag is the canonical case: passing `-o table` to a command that only allows text/json/yaml. Also typo'd enum values, region/role selectors, sort-order flags.","commonSituations":"Misremembering a command's supported formats; copy-pasting a flag value from a different CLI (kubectl -o wide vs difyctl -o wide); version drift where newer formats exist but the running binary is older; case sensitivity ('JSON' vs 'json').","solutions":["Read the hint in the error output — it lists supported values verbatim.","Run `difyctl <cmd> --help`; the outputFormat flag description enumerates allowed formats.","Match case exactly: the OutputFormat constants are lowercase ('json','yaml','text','name','wide').","Upgrade difyctl if a format you expect is missing — newer versions may have added it."],"exampleFix":"// before\ndifyctl apps list -o table     // 'table' is not a registered format\n\n// after — pick a supported format (see --help)\ndifyctl apps list -o wide\n// or\ndifyctl apps list -o json","handlingStrategy":"validation","validationCode":"// restrict the user-facing format choice to the command's declared options before invoking\nconst ALLOWED_FORMATS = ['text', 'json', 'yaml', 'name', 'wide'] as const\ntype OutFmt = (typeof ALLOWED_FORMATS)[number]\nfunction pickFormat(requested: string, allowed: readonly string[]): OutFmt {\n  if (!allowed.includes(requested)) {\n    throw new Error(`format ${requested} not in ${allowed.join(', ')}`)\n  }\n  return requested as OutFmt\n}","typeGuard":"function isAllowedValue<T extends string>(v: string, allowed: readonly T[]): v is T {\n  return (allowed as readonly string[]).includes(v)\n}","tryCatchPattern":null,"preventionTips":["Drive -o choices from `difyctl <cmd> --help`, which lists the supported values.","Centralize the allowed-formats list in your wrapper so you can't pass an unsupported one.","Treat a new format appearing in docs as version-dependent — verify with --version."],"tags":["cli","flags","enum","validation","output-format"],"backgroundTag":null,"analyzedSha":"ef8544b173fd6cd7a8e71df2cab576e52bebbfbc","analyzedAt":"2026-08-12T05:15:17.394Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}