open-webui/open-webui · error · RuntimeError

pgvector collection is not configured

Error message

pgvector collection is not configured

What it means

Raised by _retrieve_pgvector when knowledge.meta.external.source.name is empty. In the pgvector path this value is used (along with table_name/collection_field from source_config) to locate the row set to search in Postgres; without a collection name the SQL cannot be scoped. The knowledge entry's external metadata is incomplete.

Source

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

async def _retrieve_pgvector(connection, auth_config, knowledge, query, count, embedding_function) -> list[dict]:
    try:
        import psycopg
        from pgvector.psycopg import register_vector
        from psycopg.rows import dict_row
    except ImportError as exc:
        raise RuntimeError('psycopg and pgvector are required for pgvector retrieval') 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('pgvector collection is not configured')
    source_config = _source_config(knowledge)
    table_name = source_config.get('table_name') or 'document_chunk'
    collection_field = source_config.get('collection_field') or 'collection_name'
    content_field = source_config.get('content_field') or 'text'
    vector_field = source_config.get('vector_field') or 'vector'
    metadata_field = source_config.get('metadata_field') or 'vmetadata'
    document_id_field = source_config.get('document_id_field') or 'id'

    vector = await embedding_function(query, prefix=RAG_EMBEDDING_QUERY_PREFIX)

    def _search():
        from psycopg import sql

        table_identifier = sql.SQL('.').join(
            sql.Identifier(_safe_identifier(part, 'table name')) for part in table_name.split('.')
        )
        collection_identifier = sql.Identifier(_safe_identifier(collection_field, 'collection field'))
        content_identifier = sql.Identifier(_safe_identifier(content_field, 'content field'))

View on GitHub (pinned to 01f4282f1f)

Solutions

1. Set meta.external.source.name on the knowledge entry to the collection identifier stored in the configured collection_field (default column collection_name) of the target table.
2. Verify rows exist for that value: SELECT DISTINCT collection_name FROM document_chunk; using the configured table/column names.
3. PATCH the knowledge entry via API if the UI cannot edit it.
4. Require source.name at knowledge save time to prevent incomplete entries.

Example fix

# before
meta = {"external": {"connection_id": "pg-1"}}

# after
meta = {"external": {"connection_id": "pg-1", "source": {"name": "kb_finance"}}}

collection = ((knowledge.meta or {}).get('external', {}).get('source') or {}).get('name')
if not collection:
    raise ValueError('Set meta.external.source.name (collection identifier) for pgvector retrieval')

# optional DB-side check
import psycopg
with psycopg.connect(conninfo, row_factory=psycopg.rows.dict_row) as conn:
    row = conn.execute(
        'SELECT 1 FROM document_chunk WHERE collection_name = %s LIMIT 1', (collection,)
    ).fetchone()
    if not row:
        raise ValueError(f'No rows in document_chunk for collection {collection!r}')

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

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

When it happens

Trigger: Retrieval with a KnowledgeModel whose meta.external.source.name is missing/empty while the connection provider is 'pgvector'.

Common situations: Knowledge entry created without the collection name; the collection value in Postgres changed but the meta was blanked; API scripts writing meta.external without the source object.

Related errors

• External source collection is not configured
• Milvus collection is not configured
• External knowledge connection is not configured
• Pgvector requires setting PGVECTOR_DB_URL or using Postgres
• PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH is set to {PGVECTOR_IN

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