FlowiseAI/Flowise · error · Error

The Collection's primaryField is configured with autoId=fals

Error message

The Collection's primaryField is configured with autoId=false, thus its value must be provided through metadata.

What it means

Thrown during Milvus upsert/insert when the collection's primary key field is configured with `autoId=false` but the document's metadata does not contain a value under the `primaryField` key. Milvus requires an explicit primary key value when auto-ID generation is disabled, and this node sources that value exclusively from `doc.metadata[primaryField]`.

Source

Thrown at packages/components/nodes/vectorstores/Milvus/Milvus.ts:436

            return
        }
        await this.ensureCollection(vectors, documents)

        const insertDatas: InsertRow[] = []

        for (let index = 0; index < vectors.length; index++) {
            const vec = vectors[index]
            const doc = documents[index]
            const data: InsertRow = {
                [this.textField]: doc.pageContent,
                [this.vectorField]: vec
            }
            this.fields.forEach((field) => {
                switch (field) {
                    case this.primaryField:
                        if (!this.autoId) {
                            if (doc.metadata[this.primaryField] === undefined) {
                                throw new Error(
                                    `The Collection's primaryField is configured with autoId=false, thus its value must be provided through metadata.`
                                )
                            }
                            data[field] = doc.metadata[this.primaryField]
                        }
                        break
                    case this.textField:
                        data[field] = doc.pageContent
                        break
                    case this.vectorField:
                        data[field] = vec
                        break
                    default: // metadata fields
                        if (doc.metadata[field] === undefined) {
                            throw new Error(`The field "${field}" is not provided in documents[${index}].metadata.`)
                        } else if (typeof doc.metadata[field] === 'object') {
                            data[field] = JSON.stringify(doc.metadata[field])
                        } else {

View on GitHub (pinned to abe4a8601a)

Solutions

Set `doc.metadata[this.primaryField]` to a unique value for every document before calling addVectors.
Enable `autoId=true` on the Milvus collection so IDs are generated server-side and this branch is skipped.
Verify the configured primary field name exactly matches the collection schema field (case-sensitive).
If using a loader/upstream node, ensure it preserves or injects the primary-key metadata.

Example fix

// before — metadata lacks the primary key
const docs = texts.map(t => new Document({ pageContent: t, metadata: {} }))
// after — inject a unique primary key for each doc
const docs = texts.map((t, i) => new Document({
    pageContent: t,
    metadata: { [primaryField]: `doc-${i}-${Date.now()}` }
}))

Defensive patterns

Strategy: validation

Validate before calling

function validatePrimaryKeys(docs: Document[], primaryField: string, autoId: boolean) {
  if (autoId) return
  const missing = docs
    .map((d, i) => (d.metadata?.[primaryField] === undefined ? i : -1))
    .filter(i => i >= 0)
  if (missing.length) throw new Error(`Missing '${primaryField}' in metadata for docs at indices: ${missing.join(', ')}`)
}

Type guard

function hasPrimaryKey(doc: Document, primaryField: string): boolean {
  const v = doc.metadata?.[primaryField]
  return v !== undefined && v !== null && v !== ''
}

Try / catch

try {
  validatePrimaryKeys(documents, this.primaryField, this.autoId)
  await store.addVectors(vectors, documents)
} catch (e) {
  throw e instanceof Error ? e : new Error(String(e))
}

Prevention

If autoId=false, inject a unique primary key into every document's metadata before insert.
Use a consistent id-generator (e.g. uuid) to avoid collisions.
Validate the primary field name matches the collection schema (case-sensitive).
Add a preflight check listing documents missing the key.

When it happens

Trigger: Adding documents via `addVectors`/upsert to a Milvus collection whose schema declares the primary field as a non-auto-generated ID, while the supplied `Document.metadata` object lacks the primary-field key. Also triggered when the field name is misconfigured (e.g. `id` vs `pk`) so the lookup misses.

Common situations: User created a collection with an explicit-ID primary key in Milvus and then pointed Flowise at it without injecting IDs into document metadata; primary field was renamed in the schema but the node config still references the old name; documents ingested from a loader that strips metadata.

Related errors

AI-assisted analysis of FlowiseAI/Flowise@abe4a8601a (2026-08-12). Data as JSON: /api/errors/04e0994bd045311f. Report an issue: GitHub.