langgenius/dify · error · Error

flag ${label} expects a value

Error message

flag ${label} expects a value

What it means

A bare Error from parseArgv (flags.ts:223) when a non-boolean flag's value is missing. The resolver already consumed the flag token; it then reads the next argv slot. If there is no next token (flag at end) OR the next token starts with '-' (looks like another flag), the resolver refuses to consume it and throws. Note: a negative-number-looking value (`-1`) is treated as a flag and rejected too — a known edge case for the parser.

Source

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

      positional.push(token)
      continue
    }

    const { name, def, label, inlineRaw } = resolved

    if (def.type === 'boolean') {
      flags[name] = inlineRaw === undefined ? true : coerceFlagValue(inlineRaw, def)
      continue
    }

    let raw: string
    if (inlineRaw !== undefined) {
      raw = inlineRaw
    } else {
      i++
      const next = i < argv.length ? argv[i] : undefined
      if (next === undefined || next.startsWith('-'))
        throw new Error(`flag ${label} expects a value`)
      raw = next
    }

    validateFlagOptions(name, raw, def)
    accumulateFlagValue(flags, name, coerceFlagValue(raw, def), def)
  }

  const args: ParsedArgs = {}
  for (let j = 0; j < argDefs.length; j++) {
    const entry = argDefs[j]
    if (!entry) continue

    const [argName, argDef] = entry
    if (j < positional.length) {
      args[argName] = positional[j]
    } else if (argDef.required) {
      throw new Error(`missing required argument: ${argName}`)
    }

View on GitHub (pinned to ef8544b173)

Solutions

1. Provide the value: `--host https://example.com`.
2. Use inline `=` form for values that look like flags: `--limit=-5`, `--id=-ws-abc`.
3. Use `--` to mark end of flags if you must pass a leading-dash positional, though note parseArgv stops flag parsing entirely after `--`.
4. Quote/ensure shell variables are non-empty before interpolation.

Example fix

// before — value missing / looks like a flag
difyctl apps list --host
difyctl apps list --limit -5

// after
difyctl apps list --host https://cloud.dify.ai
difyctl apps list --limit=-5

// ensure every value-taking flag has a non-dashy next token before invoking
function ensureFlagValues(argv: string[], valueFlags: ReadonlySet<string>): void {
  for (let i = 0; i < argv.length; i++) {
    const t = argv[i]!
    const name = t.startsWith('--') ? t.split('=')[0] : t
    if (valueFlags.has(name)) {
      const inline = t.includes('=')
      const next = argv[i + 1]
      if (!inline && (next === undefined || next.startsWith('-'))) {
        throw new Error(`${name} requires a value`)
      }
    }
  }
}

When it happens

Trigger: `difyctl apps list --host` (nothing after); `difyctl ... --host --verbose` (next token is a flag); `--limit -5` (the -5 looks like a flag). Boolean flags are exempt because they don't consume a value (flags.ts:211-213).

Common situations: Truncated copy-paste of a command; shell variable that expanded to empty (`--host=$HOST` with HOST unset); values that legitimately start with '-' (negative numbers, dashed IDs) being mistaken for flags.

Related errors

• unknown flag: --${name}
• unknown flag: -${char}
• 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/010385dac239d027. Report an issue: GitHub.