open-webui/open-webui · error · ValueError

Cannot create Milvus collection without items to determine v

Error message

Cannot create Milvus collection without items to determine vector dimension.

What it means

Raised by MilvusClient.insert when the target collection does not exist yet and the items list is empty. Milvus collections require a fixed vector dimension at creation, and this client derives it from len(items[0]['vector']); with zero items there is no dimension to infer, so creating on-first-insert is impossible and the call fails fast instead of creating a broken collection.

Source

Thrown at backend/open_webui/retrieval/vector/dbs/milvus.py:273

        # Get all the items in the collection. This can be very resource-intensive for large collections.
        collection_name = collection_name.replace('-', '_')
        log.warning(
            f"Fetching ALL items from collection '{self.collection_prefix}_{collection_name}'. This might be slow for large collections."
        )
        # Using query with a trivial filter to get all items.
        # This will use the paginated query logic.
        return self.query(collection_name=collection_name, filter={}, limit=-1)

    def insert(self, collection_name: str, items: list[VectorItem]):
        # Insert the items into the collection, if the collection does not exist, it will be created.
        collection_name = collection_name.replace('-', '_')
        if not self.client.has_collection(collection_name=f'{self.collection_prefix}_{collection_name}'):
            log.info(f'Collection {self.collection_prefix}_{collection_name} does not exist. Creating now.')
            if not items:
                log.error(
                    f'Cannot create collection {self.collection_prefix}_{collection_name} without items to determine dimension.'
                )
                raise ValueError('Cannot create Milvus collection without items to determine vector dimension.')
            self._create_collection(collection_name=collection_name, dimension=len(items[0]['vector']))

        log.info(f'Inserting {len(items)} items into collection {self.collection_prefix}_{collection_name}.')
        data = []
        for item in items:
            text = item['text'] or ''
            if len(text) > MILVUS_TEXT_MAX_LENGTH:
                log.warning(f'Milvus: truncating text id={item["id"]} {len(text)}->{MILVUS_TEXT_MAX_LENGTH} chars')
                text = text[:MILVUS_TEXT_MAX_LENGTH]
            data.append(
                {
                    'id': item['id'],
                    'vector': item['vector'],
                    'data': {'text': text},
                    'metadata': process_metadata(item['metadata']),
                }
            )
        try:

View on GitHub (pinned to 01f4282f1f)

Solutions

Check upstream: ensure the document produced at least one chunk before calling insert (verify the loader/parser output).
Skip the insert call when items is empty: if not items: return before touching the vector DB.
If the collection should exist, verify collection naming/prefix (collections are prefixed and '-' replaced by '_') — you may be checking a differently-named collection.

Example fix

# before
client.insert(collection_name='kb_docs', items=[])  # collection missing -> ValueError

# after
if items:
    client.insert(collection_name='kb_docs', items=items)
else:
    log.warning('No chunks to insert; skipping vector store write')

Defensive patterns

Strategy: validation

Validate before calling

def insertable(items: list, collection_exists: bool) -> bool:
    """Milvus auto-create needs >=1 item to infer the vector dimension."""
    return bool(items) or collection_exists

# before calling insert:
if not items and not client.client.has_collection(f'{client.collection_prefix}_{name}'):
    log.warning(f'Skipping insert into new collection {name}: no items to infer dimension')
    return

Type guard

def is_non_empty_vector_items(items: object) -> bool:
    return (
        isinstance(items, list)
        and len(items) > 0
        and all(isinstance(i, dict) and isinstance(i.get('vector'), (list, tuple)) and len(i['vector']) > 0 for i in items)
    )

Try / catch

try:
    client.insert(collection_name=name, items=items)
except ValueError as e:
    if 'without items to determine vector dimension' in str(e):
        log.warning(f'No content to store for {name}; nothing inserted')
        return []
    raise

Prevention

Filter empty chunk lists at the parsing stage — never hand the vector store an empty batch.
Fail document ingestion early with a clear user message when a document yields zero chunks.
When creating collections intentionally, pass a schema/dimension explicitly instead of relying on first-insert inference.

When it happens

Trigger: VECTOR_DB=milvus and calling insert() (e.g., saving knowledge documents) with an empty batch for a collection name that doesn't exist yet — typically a chunking/parsing step upstream produced zero chunks (empty PDF, failed extraction) on a brand-new collection.

Common situations: First upload to a knowledge base being an empty/unparseable document; ingestion pipeline bug yielding empty chunk lists; automated tests calling insert with fixtures that are empty.

Related errors

AI-assisted analysis of open-webui/open-webui@01f4282f1f (2026-08-14). Data as JSON: /api/errors/d84b7edf443a9e73. Report an issue: GitHub.