{"record":{"id":"3f5ef8af2b34ff90","repo":"langgenius/dify","slug":"name-must-be-a-non-empty-string-when-set","errorCode":null,"errorMessage":"${name} must be a non-empty string when set","messagePattern":"(.+?) must be a non-empty string when set","errorType":"validation","errorClass":"ValidationError","httpStatus":null,"severity":"error","filePath":"sdks/nodejs-client/src/client/validation.ts","lineNumber":29,"sourceCode":"  }\n  if (value.length > MAX_STRING_LENGTH) {\n    throw new ValidationError(`${name} exceeds maximum length of ${MAX_STRING_LENGTH} characters`)\n  }\n}\n\n/**\n * Validates optional string fields that must be non-empty when provided.\n * Use this for fields like `name` that are optional but should not be empty strings.\n *\n * For filter parameters that accept empty strings (e.g., `keyword: \"\"`),\n * use `validateParams` which allows empty strings for optional params.\n */\nexport function ensureOptionalString(value: unknown, name: string): void {\n  if (value === undefined || value === null) {\n    return\n  }\n  if (typeof value !== 'string' || value.trim().length === 0) {\n    throw new ValidationError(`${name} must be a non-empty string when set`)\n  }\n  if (value.length > MAX_STRING_LENGTH) {\n    throw new ValidationError(`${name} exceeds maximum length of ${MAX_STRING_LENGTH} characters`)\n  }\n}\n\nexport function ensureOptionalInt(value: unknown, name: string): void {\n  if (value === undefined || value === null) {\n    return\n  }\n  if (!Number.isInteger(value)) {\n    throw new ValidationError(`${name} must be an integer when set`)\n  }\n}\n\nexport function ensureOptionalBoolean(value: unknown, name: string): void {\n  if (value === undefined || value === null) {\n    return","sourceCodeStart":11,"sourceCodeEnd":47,"githubUrl":"https://github.com/langgenius/dify/blob/ef8544b173fd6cd7a8e71df2cab576e52bebbfbc/sdks/nodejs-client/src/client/validation.ts#L11-L47","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Pass undefined (or omit the key) instead of '' when you want to leave the field unchanged: kb.updateDataset(ds, { name: undefined }).","Normalize form input upstream: const name = raw.trim() || undefined.","Ensure the value is a string before assignment when sourcing from JSON."],"exampleFix":"// before\nawait kb.updateDataset(ds, { name: form.name }) // form.name === ''\n\n// after\nawait kb.updateDataset(ds, { name: form.name?.trim() || undefined })","handlingStrategy":"validation","validationCode":"function normalizeOptionalString(value: string | undefined): string | undefined {\n  if (value === undefined) return undefined\n  const trimmed = value.trim()\n  return trimmed.length ? trimmed : undefined\n}","typeGuard":"function isOptionalNonEmptyString(value: unknown): value is string | undefined {\n  return value === undefined || value === null || (typeof value === 'string' && value.trim().length > 0)\n}","tryCatchPattern":"try {\n  await kb.updateDataset(ds, { name })\n} catch (err) {\n  if (err instanceof Error && /non-empty string when set/.test(err.message)) {\n    // retry without the field\n    await kb.updateDataset(ds, {})\n  } else throw err\n}","preventionTips":["Normalize form inputs to undefined when empty: const name = raw.trim() || undefined.","Do not conflate '' with 'no value'.","Type optional string fields as string | undefined, never string with default ''."],"tags":["validation","optional-field","string","guard"],"backgroundTag":null,"analyzedSha":"ef8544b173fd6cd7a8e71df2cab576e52bebbfbc","analyzedAt":"2026-08-12T05:15:17.394Z","schemaVersion":2},"datasetVersion":"2026-08-12T12:31:55.035Z"}