langgenius/dify · error · Error

expected integer, got ${JSON.stringify(raw)}

Error message

expected integer, got ${JSON.stringify(raw)}

What it means

A bare Error thrown by coerceFlagValue (flags.ts:91) when a flag declared with Flags.integer(...) receives a value that Number() turns into NaN. NOTE the check is only `Number.isNaN(n)` — values like '1.5', '0x10', '1e3', 'Infinity', and '' are NOT caught here because Number() parses them; only non-numeric strings throw. Also it is a plain Error (not BaseError), so it bypasses the structured error/exit-code mapping and surfaces as a generic failure.

Source

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

    Opts extends { default: number } ? number : number | undefined
  >
}

function stringArg<const Opts extends { description: string; required?: boolean }>(
  opts: Opts,
): ArgDefinition<Opts extends { required: true } ? string : string | undefined> {
  return opts as ArgDefinition<Opts extends { required: true } ? string : string | undefined>
}

export const Args = {
  string: stringArg,
}

function coerceFlagValue(raw: string, def: FlagDefinition): string | boolean | number {
  switch (def.type) {
    case 'integer': {
      const n = Number(raw)
      if (Number.isNaN(n)) throw new Error(`expected integer, got ${JSON.stringify(raw)}`)

      return n
    }
    case 'boolean': {
      if (raw === 'true' || raw === '1') return true

      if (raw === 'false' || raw === '0') return false

      throw new Error(`expected boolean, got ${JSON.stringify(raw)}`)
    }
    default:
      return raw
  }
}

function accumulateFlagValue(
  flags: ParsedFlags,
  name: string,

View on GitHub (pinned to ef8544b173)

Solutions

1. Supply a base-10 integer: `--limit=50`.
2. Quote/validate the value in your shell before passing it: `[[ "$LIMIT" =~ ^[0-9]+$ ]] && difyctl ... --limit="$LIMIT"`.
3. Check the command's --help to confirm the flag is integer-typed and which name is expected.
4. If maintaining difyctl: tighten coerceFlagValue to reject non-integers (e.g., !Number.isInteger(n) or a strict /^[+-]?\d+$/ regex) and wrap as a BaseError so the exit code is Usage (2) not Generic (1).

Example fix

// before — non-numeric trips NaN
difyctl apps list --limit=abc

// after
difyctl apps list --limit=50

// hardening suggestion for cli/src/framework/flags.ts (integer case)
case 'integer': {
  if (!/^[-+]?\d+$/.test(raw.trim()))
    throw new BaseError({ code: ErrorCode.UsageInvalidFlag, message: `expected integer, got ${JSON.stringify(raw)}` })
  return Number(raw)
}

// validate integer flag values before they reach parseArgv
function asInteger(raw: string, flag: string): number {
  if (!/^[+-]?\d+$/.test(raw.trim())) {
    throw new Error(`--${flag} expects a base-10 integer, got ${JSON.stringify(raw)}`)
  }
  return Number(raw)
}
// usage: asInteger(process.env.LIMIT ?? '', 'limit')

function isIntegerString(v: string): boolean {
  return /^[+-]?\d+$/.test(v.trim())
}

When it happens

Trigger: Passing a non-numeric token to an integer flag: `--limit=abc`, `--page foo` where foo is text, `--retry=`. The case-insensitive Number() coercion means 'NaN' literally, 'undefined', or arbitrary identifiers trip it. Floats, scientific notation, and hex slip through silently (a latent correctness bug).

Common situations: Typos in flag values; copy-pasting a value with units (`--limit=10x`); env-driven scripts interpolating an unset variable (`--page=$PAGE` where PAGE is empty or non-numeric); confusing a string flag for an integer one; shell glob expanding to a non-numeric value.

Related errors

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

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