langgenius/dify · error · ValidationError

${name} exceeds maximum size of ${MAX_LIST_LENGTH} items

Error message

${name} exceeds maximum size of ${MAX_LIST_LENGTH} items

What it means

Thrown by ensureStringArray() in validation.ts:59 as a ValidationError when the array is valid and non-empty but its length exceeds 1000 (MAX_LIST_LENGTH). The cap defends against oversized batched queries.

Source

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

    throw new ValidationError(`${name} must be an integer when set`)
  }
}

export function ensureOptionalBoolean(value: unknown, name: string): void {
  if (value === undefined || value === null) {
    return
  }
  if (typeof value !== 'boolean') {
    throw new ValidationError(`${name} must be a boolean when set`)
  }
}

export function ensureStringArray(value: unknown, name: string): void {
  if (!Array.isArray(value) || value.length === 0) {
    throw new ValidationError(`${name} must be a non-empty string array`)
  }
  if (value.length > MAX_LIST_LENGTH) {
    throw new ValidationError(`${name} exceeds maximum size of ${MAX_LIST_LENGTH} items`)
  }
  value.forEach((item) => {
    if (typeof item !== 'string' || item.trim().length === 0) {
      throw new ValidationError(`${name} must contain non-empty strings`)
    }
  })
}

export function ensureOptionalStringArray(value: unknown, name: string): void {
  if (value === undefined || value === null) {
    return
  }
  ensureStringArray(value, name)
}

export function ensureRating(value: unknown): void {
  if (value === undefined || value === null) {
    return

View on GitHub (pinned to ef8544b173)

Solutions

1. Batch the request: for (const chunk of chunkArray(tagIds, 1000)) await kb.listDatasets({ tagIds: chunk }).
2. Reduce the selection upstream; rarely does a real query need >1000 tags.
3. Validate the size before calling and surface a user-facing error if exceeded.

Example fix

// before
await kb.listDatasets({ tagIds: allTags }) // allTags.length === 5000

// after
for (const chunk of chunk(allTags, 1000)) {
  await kb.listDatasets({ tagIds: chunk })
}

function chunk<T>(arr: T[], size = 1000): T[][] {
  const out: T[][] = []
  for (let i = 0; i < arr.length; i += size) out.push(arr.slice(i, i + size))
  return out
}

function isBoundedStringArray(value: unknown, max = 1000): value is string[] {
  return Array.isArray(value) && value.length <= max
}

try {
  await kb.listDatasets({ tagIds })
} catch (err) {
  if (err instanceof Error && /exceeds maximum size/.test(err.message)) {
    for (const c of chunk(tagIds as string[], 1000)) await kb.listDatasets({ tagIds: c })
  } else throw err
}

When it happens

Trigger: Calling kb.listDatasets({ tagIds: hugeArray }) where hugeArray.length > 1000. The non-empty check passes, then the cap check at validation.ts:58 fires.

Common situations: Bulk fetching by tag without pagination; concatenating many tag lists; passing an unbounded UI selection directly to the SDK.

Related errors

• Parameter '${key}' exceeds maximum size of ${MAX_LIST_LENGTH
• ${name} must be a non-empty string array
• ${name} must contain non-empty strings
• ${name} exceeds maximum length of ${MAX_STRING_LENGTH} chara
• ${name} must be an integer when set

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