{"record":{"id":"268b03f6bdbdab07","repo":"langgenius/dify","slug":"name-must-be-a-boolean-when-set","errorCode":null,"errorMessage":"${name} must be a boolean when set","messagePattern":"(.+?) must be a boolean when set","errorType":"validation","errorClass":"ValidationError","httpStatus":null,"severity":"error","filePath":"sdks/nodejs-client/src/client/validation.ts","lineNumber":50,"sourceCode":"    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\n  }\n  if (typeof value !== 'boolean') {\n    throw new ValidationError(`${name} must be a boolean when set`)\n  }\n}\n\nexport function ensureStringArray(value: unknown, name: string): void {\n  if (!Array.isArray(value) || value.length === 0) {\n    throw new ValidationError(`${name} must be a non-empty string array`)\n  }\n  if (value.length > MAX_LIST_LENGTH) {\n    throw new ValidationError(`${name} exceeds maximum size of ${MAX_LIST_LENGTH} items`)\n  }\n  value.forEach((item) => {\n    if (typeof item !== 'string' || item.trim().length === 0) {\n      throw new ValidationError(`${name} must contain non-empty strings`)\n    }\n  })\n}\n\nexport function ensureOptionalStringArray(value: unknown, name: string): void {","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/langgenius/dify/blob/ef8544b173fd6cd7a8e71df2cab576e52bebbfbc/sdks/nodejs-client/src/client/validation.ts#L32-L68","documentation":"Thrown by ensureOptionalBoolean() in validation.ts:50 as a ValidationError. Optional boolean fields such as includeAll on listDatasets may be omitted, but when present must be a real boolean. Truthy/falsy values like 'true', 0, 1, 'yes' are rejected because typeof !== 'boolean'.","triggerScenarios":"Calling kb.listDatasets({ includeAll: 'true' }) (string from env or query), { includeAll: 1 }, { includeAll: 'yes' }. Undefined/null accepted via early return at validation.ts:47.","commonSituations":"Reading includeAll from an env var or HTTP query string (always string); passing 0/1 from a checkbox serializer; coercing through Boolean('false') which yields true.","solutions":["Coerce explicitly: const includeAll = raw === 'true' ? true : raw === 'false' ? false : undefined.","Avoid Boolean(raw) — Boolean('false') is true; parse the literal string instead.","Set the upstream type to boolean | undefined so non-booleans fail at compile time."],"exampleFix":"// before\nawait kb.listDatasets({ includeAll: process.env.INCLUDE_ALL })\n\n// after\nconst raw = process.env.INCLUDE_ALL\nconst includeAll = raw === 'true' ? true : raw === 'false' ? false : undefined\nawait kb.listDatasets({ includeAll })","handlingStrategy":"validation","validationCode":"function toOptionalBoolean(value: unknown): boolean | undefined {\n  if (value === undefined || value === null) return undefined\n  if (value === true || value === false) return value\n  if (value === 'true') return true\n  if (value === 'false') return false\n  throw new Error('value must be a boolean when set')\n}","typeGuard":"function isOptionalBoolean(value: unknown): value is boolean | undefined {\n  return value === undefined || value === null || typeof value === 'boolean'\n}","tryCatchPattern":"try {\n  await kb.listDatasets({ includeAll })\n} catch (err) {\n  if (err instanceof Error && /must be a boolean when set/.test(err.message)) {\n    await kb.listDatasets({ includeAll: String(includeAll) === 'true' })\n  } else throw err\n}","preventionTips":["Parse env/query strings to booleans explicitly, never with Boolean().","Type optional boolean fields as boolean | undefined in your layer.","Document the canonical 'true'/'false' string form if your config source is text."],"tags":["validation","optional-field","boolean","coercion","env"],"backgroundTag":null,"analyzedSha":"ef8544b173fd6cd7a8e71df2cab576e52bebbfbc","analyzedAt":"2026-08-12T05:15:17.394Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}