open-webui/open-webui · error · RuntimeError

External source collection is not configured

Error message

External source collection is not configured

What it means

Raised by _retrieve_qdrant when knowledge.meta.external.source.name is empty or missing. That field names the Qdrant collection to query, so without it the code has no target to run query_points against. It indicates the knowledge model's external metadata was saved incompletely.

Source

Thrown at backend/open_webui/retrieval/external.py:103

        raise RuntimeError(f'Invalid {label}')
    return value


async def _retrieve_qdrant(connection, auth_config, knowledge, query, count, embedding_function) -> list[dict]:
    try:
        from qdrant_client import QdrantClient
    except ImportError as exc:
        raise RuntimeError('qdrant-client is not installed') from exc

    if not embedding_function:
        raise RuntimeError('Embedding function is not configured')

    config = connection.get('config') or {}
    external = (knowledge.meta or {}).get('external', {})
    source = external.get('source') or {}
    collection_name = source.get('name')
    if not collection_name:
        raise RuntimeError('External source collection is not configured')
    source_config = _source_config(knowledge)
    vector_field = source_config.get('vector_field') or None

    vector = await embedding_function(query, prefix=RAG_EMBEDDING_QUERY_PREFIX)

    def _search():
        client = QdrantClient(
            url=connection.get('endpoint'),
            api_key=(auth_config or {}).get('api_key'),
            timeout=config.get('timeout') or 30,
        )
        return client.query_points(
            collection_name=collection_name,
            query=vector,
            using=vector_field,
            limit=count,
        )

View on GitHub (pinned to 01f4282f1f)

Solutions

  1. Open the knowledge base settings and set the external source collection name (meta.external.source.name) to an existing Qdrant collection.
  2. If managing via API, PATCH the knowledge entry so meta.external.source.name is a non-empty string matching a live collection in Qdrant.
  3. Verify the collection actually exists: use the Qdrant dashboard or QdrantClient.get_collections() and copy the exact name.
  4. Validate meta.external completeness at knowledge-create/update time so incomplete entries cannot be saved.

Example fix

# before: knowledge meta saved as
knowledge.meta = {"external": {"connection_id": "abc"}}

# after: include the source collection name
knowledge.meta = {
    "external": {
        "connection_id": "abc",
        "source": {"name": "my_collection"},
    },
}
Defensive patterns

Strategy: validation

Validate before calling

def external_source_name(knowledge) -> str | None:
    external = (knowledge.meta or {}).get('external', {})
    return (external.get('source') or {}).get('name') or None

if external_source_name(knowledge) is None:
    raise ValueError('Knowledge base needs an external source collection name')

Type guard

def has_external_source(knowledge) -> bool:
    meta = knowledge.meta or {}
    source = (meta.get('external') or {}).get('source') or {}
    return bool(source.get('name'))

Try / catch

try:
    await retrieve_external_knowledge(request, knowledge, queries, count)
except RuntimeError as e:
    if 'collection is not configured' in str(e):
        return fix_knowledge_meta_prompt(knowledge.id)
    raise

Prevention

When it happens

Trigger: A KnowledgeModel whose meta.external exists (with a connection_id) but whose meta.external.source.name is absent, empty, or None, is used in retrieval. Typical when the knowledge entry was created via API/UI without filling the external source collection name, or the meta dict was hand-edited.

Common situations: Creating an external knowledge base and skipping the 'collection name' field; importing or migrating knowledge entries with partial meta JSON; frontend bug that submits meta.external without source; renaming/deleting the collection in Qdrant and clearing the field locally.

Related errors

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