langgenius/dify · error · ValidationError

Parameter '${key}' must be an integer

Error message

Parameter '${key}' must be an integer

What it means

Thrown by validateParams() in validation.ts:116 as a ValidationError for the pagination keys 'page', 'limit', and 'page_size'. In the HTTP layer these must be integers when present. Floats, numeric strings, NaN, and booleans fail Number.isInteger().

Source

Thrown at sdks/nodejs-client/src/client/validation.ts:116

    } else if (Array.isArray(value)) {
      if (value.length > MAX_LIST_LENGTH) {
        throw new ValidationError(
          `Parameter '${key}' exceeds maximum size of ${MAX_LIST_LENGTH} items`,
        )
      }
    } else if (isRecord(value)) {
      if (Object.keys(value).length > MAX_DICT_LENGTH) {
        throw new ValidationError(
          `Parameter '${key}' exceeds maximum size of ${MAX_DICT_LENGTH} items`,
        )
      }
    }

    if (key === 'user' && typeof value !== 'string') {
      throw new ValidationError(`Parameter '${key}' must be a string`)
    }
    if ((key === 'page' || key === 'limit' || key === 'page_size') && !Number.isInteger(value)) {
      throw new ValidationError(`Parameter '${key}' must be an integer`)
    }
    if (key === 'files' && !Array.isArray(value) && typeof value !== 'object') {
      throw new ValidationError(`Parameter '${key}' must be a list or dict`)
    }
    if (key === 'rating' && value !== 'like' && value !== 'dislike') {
      throw new ValidationError(`Parameter '${key}' must be 'like' or 'dislike'`)
    }
  })
}

View on GitHub (pinned to ef8544b173)

Solutions

  1. Coerce at the boundary: const page = rawPage ? Number(rawPage) : undefined; const limit = rawLimit ? Number(rawLimit) : undefined.
  2. Use parseInt(raw, 10) and skip when NaN.
  3. Type pagination options as number | undefined upstream so string sources fail the compiler.

Example fix

// before
await kb.listDatasets({ page: req.query.page, limit: req.query.limit }) // strings

// after
const page = req.query.page ? Number(req.query.page) : undefined
const limit = req.query.limit ? Number(req.query.limit) : undefined
await kb.listDatasets({ page, limit })
Defensive patterns

Strategy: validation

Validate before calling

function assertIntegerKeys(params: Record<string, unknown>) {
  for (const k of ['page', 'limit', 'page_size']) {
    if (k in params && params[k] !== undefined && params[k] !== null && !Number.isInteger(params[k])) {
      throw new Error(`Parameter '${k}' must be an integer`)
    }
  }
}

Type guard

function isIntegerPagination(params: Record<string, unknown>): boolean {
  return ['page', 'limit', 'page_size'].every((k) =>
    !(k in params) || params[k] === undefined || params[k] === null || Number.isInteger(params[k])
  )
}

Try / catch

try {
  await kb.listDatasets({ page, limit })
} catch (err) {
  if (err instanceof Error && /must be an integer/.test(err.message)) {
    await kb.listDatasets({
      page: page ? Number(page) : undefined,
      limit: limit ? Number(limit) : undefined,
    })
  } else throw err
}

Prevention

When it happens

Trigger: Any request carrying { page: '2' }, { limit: 1.5 }, { page_size: '20' } in query or body. Triggered from client.ts request() during validateParams, after the size checks.

Common situations: Pagination values pulled from URL query strings (always strings in HTTP); JSON config with quoted numbers; computing page from a float offset without rounding.

Related errors

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