n8n-io/n8n · error · NodeOperationError

Error inserting documents into ChromaDB: ${errorMessage}

Error message

Error inserting documents into ChromaDB: ${errorMessage}

What it means

Catch-all NodeOperationError in `populateVectorStore` for any insert failure that is NOT the dimension-mismatch case. The original Chroma SDK error message is appended. Wraps `ExtendedChroma.fromDocuments`, which is what actually adds vectors to the collection.

Source

Thrown at packages/@n8n/nodes-langchain/nodes/vector_store/VectorStoreChromaDB/VectorStoreChromaDB.node.ts:459

			const detailMessage = chromaError.response?.data?.detail;

			// Handle dimension mismatch error specifically
			if (
				errorMessage.includes('embedding with dimension') ||
				detailMessage?.includes('embedding with dimension')
			) {
				const displayMessage = detailMessage ?? errorMessage;
				throw new NodeOperationError(
					context.getNode(),
					`ChromaDB embedding dimension mismatch: ${displayMessage}`,
					{
						itemIndex,
						description:
							'The collection expects embeddings with different dimensions. Enable "Clear Collection" option to recreate the collection with correct dimensions, or use a different collection name.',
					},
				);
			}
			throw new NodeOperationError(
				context.getNode(),
				`Error inserting documents into ChromaDB: ${errorMessage}`,
				{ itemIndex },
			);
		}
	},
}) {}

View on GitHub (pinned to 5ac6606e81)

Solutions

1. Read the appended `errorMessage` to identify the server-side cause.
2. Reduce batch size or insert in smaller chunks to avoid payload/timeout limits.
3. Flatten metadata values to primitives before insert (ChromaDB rejects nested objects in some versions).
4. Retry on transient 5xx; if persistent, check ChromaDB server logs and version compatibility.

Example fix

// before
throw new NodeOperationError(
  context.getNode(),
  `Error inserting documents into ChromaDB: ${errorMessage}`,
  { itemIndex },
);

// after: hint at the two most common non-dimension causes
const isPayload = /payload|too large|413/i.test(errorMessage);
throw new NodeOperationError(
  context.getNode(),
  `Error inserting documents into ChromaDB: ${errorMessage}`,
  {
    itemIndex,
    description: isPayload
      ? 'Reduce the batch size or document size and retry.'
      : 'Check the ChromaDB server logs and metadata shapes.',
  },
);

// Pre-flight: validate document shape (metadata primitives, non-empty pageContent) before insert.
function validateDocuments(docs: Document[]): void {
  for (const d of docs) {
    if (typeof d.pageContent !== 'string' || d.pageContent.length === 0) {
      throw new Error('Each document must have non-empty string pageContent');
    }
    for (const [k, v] of Object.entries(d.metadata ?? {})) {
      if (v !== null && typeof v === 'object') {
        throw new Error(`Metadata '${k}' must be a primitive, got ${typeof v}`);
      }
    }
  }
}

function isPayloadError(error: unknown): boolean {
  return error instanceof Error && /payload|too large|413/i.test(error.message);
}

try {
  await ExtendedChroma.fromDocuments(documents, embeddings, config);
} catch (error) {
  const msg = error instanceof Error ? error.message : 'Unknown error';
  throw new NodeOperationError(context.getNode(), `Error inserting documents into ChromaDB: ${msg}`, {
    itemIndex,
    description: isPayloadError(error) ? 'Reduce batch size.' : 'Check ChromaDB logs and metadata shapes.',
  });
}

When it happens

Trigger: Insert failures other than dimension mismatch: server-side 5xx during indexing, payload too large, network reset mid-batch, invalid document IDs, metadata schema violation, rate limit from Chroma Cloud.

Common situations: Bulk inserting thousands of documents and hitting a timeout; Chroma Cloud rate limit; metadata value of an unsupported type (e.g. nested object); SSL handshake to a self-hosted instance failing intermittently.

Related errors

• Error connecting to ChromaDB: ${message}
• Failed to list ChromaDB collections: ${errorMessage}
• Collection must be a string
• ChromaDB embedding dimension mismatch: ${displayMessage}
• Error: ${error.message}

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