langgenius/dify · error · Error

unknown flag: --${name}

Error message

unknown flag: --${name}

What it means

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).

Source

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

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 }
  }

  if (token.length === 2 && token[1] !== undefined) {
    const char = token[1]
    const resolved = resolveByChar(char, flags)
    if (!resolved) throw new Error(`unknown flag: -${char}`)
    const [name, def] = resolved
    return { name, def, label: `-${char}`, inlineRaw: undefined }
  }

  return null
}

// Scans argv for a boolean flag without throwing on unknown tokens, so it is safe
// to call before the command-specific flag set is known (e.g. global flags).
export function hasBooleanFlag(argv: readonly string[], name: string, char?: string): boolean {
  for (const token of argv) {

View on GitHub (pinned to ef8544b173)

Solutions

1. Run `difyctl <cmd> --help` and copy the exact flag name.
2. For output format, remember the short form is `-o` not `--output` (defined in outputFormatFlag, flags.ts:38-48).
3. If you expected the flag to exist, check the installed version (`difyctl --version`) and upgrade.
4. If maintaining difyctl: wrap resolveToken failures in BaseError(UsageInvalidFlag) so the exit is 2 and the message is consistent.

Example fix

// before
difyctl apps list --json

// after
difyctl apps list -o json

// before constructing argv, filter through the command's known long flags
const KNOWN_LONG = new Set(['--host', '--insecure', '--verbose', '--output'])
function checkLongFlags(argv: string[]): void {
  for (const t of argv) {
    if (t.startsWith('--')) {
      const name = t.split('=')[0]!
      if (!KNOWN_LONG.has(name)) throw new Error(`unknown flag ${name}`)
    }
  }
}

function isKnownLongFlag(token: string, known: ReadonlySet<string>): boolean {
  if (!token.startsWith('--')) return true
  return known.has(token.split('=')[0]!)
}

When it happens

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

Common situations: Renamed flags between versions; habit from another tool (kubectl, gh, aws cli); autocomplete suggesting the wrong name; copy-paste from outdated docs.

Related errors

• unknown flag: -${char}
• flag ${label} expects a value
• UsageMissingArg
• expected integer, got ${JSON.stringify(raw)}
• expected boolean, got ${JSON.stringify(raw)}

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