langgenius/dify · error · UnsupportedArgValueError

unsupported argument value

Error message

unsupported argument value

What it means

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.

Source

Thrown at cli/src/framework/flags.ts:134

  } else {
    flags[name] = value
  }
}

function resolveByChar(
  char: string,
  flags: Record<string, FlagDefinition>,
): [name: string, def: FlagDefinition] | undefined {
  for (const [name, def] of Object.entries(flags)) {
    if (def.char === char) return [name, def]
  }

  return undefined
}

function validateFlagOptions(name: string, raw: string, def: FlagDefinition): void {
  if (def.options !== undefined && !def.options.includes(raw))
    throw new UnsupportedArgValueError(name, def, raw)
}

type ResolvedFlag = {
  name: string
  def: FlagDefinition
  label: string
  inlineRaw: string | undefined
}

function resolveToken(token: string, flags: Record<string, FlagDefinition>): ResolvedFlag | null {
  if (token.startsWith('--')) {
    const eqIdx = token.indexOf('=')
    const name = eqIdx !== -1 ? token.slice(2, eqIdx) : token.slice(2)
    const inlineRaw = eqIdx !== -1 ? token.slice(eqIdx + 1) : undefined
    const def = flags[name]
    if (!def) throw new Error(`unknown flag: --${name}`)
    return { name, def, label: `--${name}`, inlineRaw }
  }

View on GitHub (pinned to ef8544b173)

Solutions

1. Read the hint in the error output — it lists supported values verbatim.
2. Run `difyctl <cmd> --help`; the outputFormat flag description enumerates allowed formats.
3. Match case exactly: the OutputFormat constants are lowercase ('json','yaml','text','name','wide').
4. Upgrade difyctl if a format you expect is missing — newer versions may have added it.

Example fix

// before
difyctl apps list -o table     // 'table' is not a registered format

// after — pick a supported format (see --help)
difyctl apps list -o wide
// or
difyctl apps list -o json

// restrict the user-facing format choice to the command's declared options before invoking
const ALLOWED_FORMATS = ['text', 'json', 'yaml', 'name', 'wide'] as const
type OutFmt = (typeof ALLOWED_FORMATS)[number]
function pickFormat(requested: string, allowed: readonly string[]): OutFmt {
  if (!allowed.includes(requested)) {
    throw new Error(`format ${requested} not in ${allowed.join(', ')}`)
  }
  return requested as OutFmt
}

function isAllowedValue<T extends string>(v: string, allowed: readonly T[]): v is T {
  return (allowed as readonly string[]).includes(v)
}

When it happens

Trigger: 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.

Common situations: 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').

Related errors

• expected integer, got ${JSON.stringify(raw)}
• expected boolean, got ${JSON.stringify(raw)}
• usage_invalid_flag
• unknown flag: --${name}
• unknown flag: -${char}

AI-assisted analysis of langgenius/dify@ef8544b173 (2026-08-12). Data as JSON: /api/errors/10a07b79660c6406. Report an issue: GitHub.