langgenius/dify · error · ValidationError

${name} must be a non-empty string when set

Error message

${name} must be a non-empty string when set

What it means

Thrown by ensureOptionalString() in validation.ts:29 as a ValidationError. It validates optional string fields (name on updates, keyword on list filters, etc.) that may be omitted, but when present must be non-empty. Undefined and null are accepted (early return); any other non-string or whitespace-only value is rejected.

Source

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

  }
  if (value.length > MAX_STRING_LENGTH) {
    throw new ValidationError(`${name} exceeds maximum length of ${MAX_STRING_LENGTH} characters`)
  }
}

/**
 * Validates optional string fields that must be non-empty when provided.
 * Use this for fields like `name` that are optional but should not be empty strings.
 *
 * For filter parameters that accept empty strings (e.g., `keyword: ""`),
 * use `validateParams` which allows empty strings for optional params.
 */
export function ensureOptionalString(value: unknown, name: string): void {
  if (value === undefined || value === null) {
    return
  }
  if (typeof value !== 'string' || value.trim().length === 0) {
    throw new ValidationError(`${name} must be a non-empty string when set`)
  }
  if (value.length > MAX_STRING_LENGTH) {
    throw new ValidationError(`${name} exceeds maximum length of ${MAX_STRING_LENGTH} characters`)
  }
}

export function ensureOptionalInt(value: unknown, name: string): void {
  if (value === undefined || value === null) {
    return
  }
  if (!Number.isInteger(value)) {
    throw new ValidationError(`${name} must be an integer when set`)
  }
}

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

View on GitHub (pinned to ef8544b173)

Solutions

  1. Pass undefined (or omit the key) instead of '' when you want to leave the field unchanged: kb.updateDataset(ds, { name: undefined }).
  2. Normalize form input upstream: const name = raw.trim() || undefined.
  3. Ensure the value is a string before assignment when sourcing from JSON.

Example fix

// before
await kb.updateDataset(ds, { name: form.name }) // form.name === ''

// after
await kb.updateDataset(ds, { name: form.name?.trim() || undefined })
Defensive patterns

Strategy: validation

Validate before calling

function normalizeOptionalString(value: string | undefined): string | undefined {
  if (value === undefined) return undefined
  const trimmed = value.trim()
  return trimmed.length ? trimmed : undefined
}

Type guard

function isOptionalNonEmptyString(value: unknown): value is string | undefined {
  return value === undefined || value === null || (typeof value === 'string' && value.trim().length > 0)
}

Try / catch

try {
  await kb.updateDataset(ds, { name })
} catch (err) {
  if (err instanceof Error && /non-empty string when set/.test(err.message)) {
    // retry without the field
    await kb.updateDataset(ds, {})
  } else throw err
}

Prevention

When it happens

Trigger: Calling kb.listDatasets({ keyword: '' }) is allowed via validateParams, but calling kb.updateDataset(ds, { name: '' }) or { name: ' ' } hits ensureOptionalString and throws. Also fires when an optional field is set to a non-string type (number, object).

Common situations: Form submissions that send empty strings for 'no change' instead of undefined; trimming user input to '' before passing through; assigning a number to a name field by mistake.

Related errors

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