{"record":{"id":"789fa33b63de9724","repo":"n8n-io/n8n","slug":"documents-must-be-an-array","errorCode":null,"errorMessage":"Documents must be an array","messagePattern":"Documents must be an array","errorType":"validation","errorClass":"NodeOperationError","httpStatus":null,"severity":"error","filePath":"packages/@n8n/ai-utilities/src/utils/embeddings-input-validation.ts","lineNumber":34,"sourceCode":"\t\t\tdescription:\n\t\t\t\t'The text provided for embedding is empty or undefined. This can happen when: the input expression evaluates to undefined, the AI agent calls a tool without proper arguments, or a required field is missing.',\n\t\t});\n\t}\n\treturn query;\n}\n\n/**\n * Validates documents input for embedDocuments operations.\n * Throws NodeOperationError if documents array is invalid or contains invalid entries.\n *\n * @param documents - The documents array to validate\n * @param node - The node for error context\n * @returns The validated documents array\n * @throws NodeOperationError if documents is not an array or contains invalid entries\n */\nexport function validateEmbedDocumentsInput(documents: unknown, node: INode): string[] {\n\tif (!Array.isArray(documents)) {\n\t\tthrow new NodeOperationError(node, 'Documents must be an array', {\n\t\t\tdescription: 'Expected an array of strings to embed.',\n\t\t});\n\t}\n\n\tconst invalidIndex = documents.findIndex(\n\t\t(doc) => doc === undefined || doc === null || doc === '',\n\t);\n\n\tif (invalidIndex !== -1) {\n\t\tthrow new NodeOperationError(node, `Invalid document at index ${invalidIndex}`, {\n\t\t\tdescription: `Document at index ${invalidIndex} is empty or undefined. All documents must be non-empty strings.`,\n\t\t});\n\t}\n\n\treturn documents;\n}\n","sourceCodeStart":16,"sourceCodeEnd":51,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/@n8n/ai-utilities/src/utils/embeddings-input-validation.ts#L16-L51","documentation":"validateEmbedDocumentsInput() guards embedDocuments(): documents must be an array. Because the embed call iterates the array, a non-array (string, object, undefined) would either mis-embed or crash deeper, so it fails fast with a NodeOperationError pointing at the expected shape (array of strings).","triggerScenarios":"The documents input is a single string instead of an array; an object; undefined because the source expression resolved to nothing; a previous node emitted a single item where an array of items was expected.","commonSituations":"Mapping `$json.text` (a string) instead of `$json.lines` (array) into the documents input; a Split-In-Batches/aggregate mismatch; an expression returning undefined; a tool returning a single doc instead of a list.","solutions":["Provide an array of strings: wrap a single value with `[$json.text]` or use an aggregate node.","Validate before the embedding node: `if (!Array.isArray(docs)) ...`.","Check the upstream node's output type and adjust the mapping."],"exampleFix":"// before\nawait embedDocuments($json.singleText, ...);\n\n// after\nawait embedDocuments([$json.singleText], ...);","handlingStrategy":"validation","validationCode":"import { validateEmbedDocumentsInput } from '@n8n/ai-utilities';\n// or inline:\nfunction isStringArray(v: unknown): v is string[] {\n  return Array.isArray(v) && v.every((x) => typeof x === 'string');\n}\nif (!isStringArray(docs)) {\n  throw new Error('documents must be an array of strings');\n}","typeGuard":"function isStringArray(v: unknown): v is string[] {\n  return Array.isArray(v) && v.every((x) => typeof x === 'string');\n}","tryCatchPattern":null,"preventionTips":["Wrap single values with `[value]` before mapping into the documents input.","Check upstream node output type — use aggregate/split nodes to produce arrays.","Validate with isStringArray before the embedding node."],"tags":["embeddings","validation","user-error","ai-utilities"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}