langgenius/dify · error · ValidationError

${name} must be a non-empty array

Error message

${name} must be a non-empty array

What it means

Thrown by the private ensureNonEmptyArray() helper in knowledge-base.ts:52 as a ValidationError. It guards two payload fields: request.segments in createSegments() and request.operation_data in updateDocumentsMetadata(). The value must be an Array with length > 0; null, undefined, non-arrays, and empty arrays all fail.

Source

Thrown at sdks/nodejs-client/src/client/knowledge-base.ts:52

import { isFormData } from '../http/form-data'
import { DifyClient } from './base'
import {
  ensureNonEmptyString,
  ensureOptionalBoolean,
  ensureOptionalInt,
  ensureOptionalString,
  ensureStringArray,
} from './validation'

function ensureFormData(form: unknown, context: string): asserts form is SdkFormData {
  if (!isFormData(form)) {
    throw new FileUploadError(`${context} requires FormData`)
  }
}

const ensureNonEmptyArray = (value: unknown, name: string): void => {
  if (!Array.isArray(value) || value.length === 0) {
    throw new ValidationError(`${name} must be a non-empty array`)
  }
}

export class KnowledgeBaseClient extends DifyClient {
  async listDatasets(options?: DatasetListOptions): Promise<DifyResponse<KnowledgeBaseResponse>> {
    ensureOptionalInt(options?.page, 'page')
    ensureOptionalInt(options?.limit, 'limit')
    ensureOptionalString(options?.keyword, 'keyword')
    ensureOptionalBoolean(options?.includeAll, 'includeAll')

    const query: QueryParams = {
      page: options?.page,
      limit: options?.limit,
      keyword: options?.keyword ?? undefined,
      include_all: options?.includeAll ?? undefined,
    }

    if (options?.tagIds && options.tagIds.length > 0) {

View on GitHub (pinned to ef8544b173)

Solutions

1. Populate the array with at least one valid item: kb.createSegments(ds, doc, { segments: [{ content: '...' }] }).
2. Guard at the call site: if (segments.length) await kb.createSegments(...); else skip — the API does not accept no-op creates.
3. For updateDocumentsMetadata, ensure operation_data contains at least one { document_id, metadata_list } entry.
4. Double-check the request object key spelling matches the SDK's expected field name.

Example fix

// before
await kb.createSegments(ds, doc, { segments: filtered }) // filtered === []

// after
if (filtered.length) {
  await kb.createSegments(ds, doc, { segments: filtered })
}

function assertNonEmpty<T>(value: unknown, name: string): asserts value is T[] {
  if (!Array.isArray(value) || value.length === 0) throw new Error(`${name} must be a non-empty array`)
}

function isNonEmptyArray<T>(value: unknown): value is T[] {
  return Array.isArray(value) && value.length > 0
}

try {
  await kb.createSegments(ds, doc, { segments })
} catch (err) {
  if (err instanceof Error && err.name === 'ValidationError' && /non-empty array/.test(err.message)) {
    // skip the call when there is nothing to create
  } else throw err
}

When it happens

Trigger: Calling kb.createSegments(datasetId, documentId, { segments: [] }) or kb.createSegments(..., { segments: undefined }); similarly kb.updateDocumentsMetadata(datasetId, { operation_data: [] }) or with operation_data missing. The guard at knowledge-base.ts:51 rejects the value before the POST.

Common situations: Filtering segments down to zero results and passing the emptied array; mapping a list and producing [] when source data was empty; renaming the field (segments vs segment_list); forgetting the operation_data key when constructing metadata updates.

Related errors

• text or message_id is required
• ${context} requires FormData
• metadata must be one of all, only, without
• ${name} must be a non-empty string
• ${name} must be a non-empty string array

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