n8n-io/n8n · error · NodeOperationError

Single document per item expected

Error message

Single document per item expected

What it means

Cardinality-validation error in handleUpdateOperation, raised as NodeOperationError. Update replaces one existing document by ID, so it fires when document processing produced zero or multiple documents for the item instead of exactly one. The count check runs after processDocument, before the store client is asked to update.

Solutions

1. Ensure each input item resolves to exactly one document when the update operation runs.
2. Split or flatten input items so one document is produced per item.
3. Check the loader configuration: loading a binary file that yields multiple chunks violates the one-document requirement.

When it happens

Trigger: Thrown at packages/@n8n/ai-utilities/src/utils/vector-store/createVectorStoreNode/operations/updateOperation.ts:58 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of n8n-io/n8n@5ac6606e81 (2026-08-12). Data as JSON: /api/errors/bd64e2f66a0b1fce. Report an issue: GitHub.

Appendix: source

Thrown at packages/@n8n/ai-utilities/src/utils/vector-store/createVectorStoreNode/operations/updateOperation.ts:58

		// Get the document ID to update
		const documentId = context.getNodeParameter('id', itemIndex, '', {
			extractValue: true,
		}) as string;

		// Get the vector store client
		const vectorStore = await args.getVectorStoreClient(context, undefined, embeddings, itemIndex);

		try {
			// Process the document from the input
			const { processedDocuments, serializedDocuments } = await processDocument(
				loader,
				itemData,
				itemIndex,
			);

			// Validate that we have exactly one document to update
			if (processedDocuments?.length !== 1) {
				throw new NodeOperationError(context.getNode(), 'Single document per item expected');
			}

			// Add the serialized document to the result
			resultData.push(...serializedDocuments);

			// Use document ID to update the existing document
			await vectorStore.addDocuments(processedDocuments, {
				ids: [documentId],
			});

			// Log the AI event for analytics
			logAiEvent(context, 'ai-vector-store-updated');
		} finally {
			// Release the vector store client if a release method was provided
			args.releaseVectorStoreClient?.(vectorStore);
		}
	}

View on GitHub (pinned to 5ac6606e81)