open-webui/open-webui · critical · ValueError

PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH is set to {PGVECTOR_IN

Error message

PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH is set to {PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH}, which exceeds the 2000 dimension limit of the 'vector' type. Set PGVECTOR_USE_HALFVEC=true to enable the 'halfvec' type required for high-dimensional embeddings.

What it means

Import-time config validation for pgvector column type: Postgres 'vector' columns max out at 2000 dimensions, so when PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH exceeds 2000 you must opt into the 'halfvec' type (PGVECTOR_USE_HALFVEC=true) or startup fails. halfvec stores 4-bit-precision halves allowing up to 4000 dims.

Source

Thrown at backend/open_webui/config.py:648

ELASTICSEARCH_CA_CERTS = os.getenv('ELASTICSEARCH_CA_CERTS', None)
ELASTICSEARCH_API_KEY = os.getenv('ELASTICSEARCH_API_KEY', None)
ELASTICSEARCH_USERNAME = os.getenv('ELASTICSEARCH_USERNAME', None)
ELASTICSEARCH_PASSWORD = os.getenv('ELASTICSEARCH_PASSWORD', None)
ELASTICSEARCH_CLOUD_ID = os.getenv('ELASTICSEARCH_CLOUD_ID', None)
SSL_ASSERT_FINGERPRINT = os.getenv('SSL_ASSERT_FINGERPRINT', None)
ELASTICSEARCH_INDEX_PREFIX = os.getenv('ELASTICSEARCH_INDEX_PREFIX', 'open_webui_collections')
# Pgvector
PGVECTOR_DB_URL = os.getenv('PGVECTOR_DB_URL', DATABASE_URL)
if VECTOR_DB == 'pgvector' and not PGVECTOR_DB_URL.startswith('postgres'):
    raise ValueError(
        'Pgvector requires setting PGVECTOR_DB_URL or using Postgres with vector extension as the primary database.'
    )
PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH = int(os.getenv('PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH', '1536'))

PGVECTOR_USE_HALFVEC = os.getenv('PGVECTOR_USE_HALFVEC', 'false').lower() == 'true'

if PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH > 2000 and not PGVECTOR_USE_HALFVEC:
    raise ValueError(
        'PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH is set to '
        f'{PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH}, which exceeds the 2000 dimension limit of the '
        "'vector' type. Set PGVECTOR_USE_HALFVEC=true to enable the 'halfvec' "
        'type required for high-dimensional embeddings.'
    )

PGVECTOR_CREATE_EXTENSION = os.getenv('PGVECTOR_CREATE_EXTENSION', 'true').lower() == 'true'
PGVECTOR_PGCRYPTO = os.getenv('PGVECTOR_PGCRYPTO', 'false').lower() == 'true'
PGVECTOR_PGCRYPTO_KEY = os.getenv('PGVECTOR_PGCRYPTO_KEY', None)
if PGVECTOR_PGCRYPTO and not PGVECTOR_PGCRYPTO_KEY:
    raise ValueError('PGVECTOR_PGCRYPTO is enabled but PGVECTOR_PGCRYPTO_KEY is not set. Please provide a valid key.')


PGVECTOR_POOL_SIZE = os.getenv('PGVECTOR_POOL_SIZE', None)

if PGVECTOR_POOL_SIZE != None:
    try:
        PGVECTOR_POOL_SIZE = int(PGVECTOR_POOL_SIZE)

View on GitHub (pinned to 01f4282f1f)

Solutions

Set PGVECTOR_USE_HALFVEC=true to use halfvec and support up to 4000 dimensions (tiny precision loss, ~50% storage saving)
Or reduce PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH to <= 2000 if your embedding model fits
Verify your pgvector extension version supports halfvec (>= 0.7)

Example fix

# before
VECTOR_DB=pgvector
PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH=3072  # raises
# after
VECTOR_DB=pgvector
PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH=3072
PGVECTOR_USE_HALFVEC=true

Defensive patterns

Strategy: validation

Validate before calling

dim = int(os.getenv('PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH', '1536'))
half = os.getenv('PGVECTOR_USE_HALFVEC', 'false').lower() == 'true'
if os.getenv('VECTOR_DB') == 'pgvector' and dim > 2000 and not half:
    raise SystemExit('Set PGVECTOR_USE_HALFVEC=true for dims > 2000')

Try / catch

try:
    import open_webui.config
except ValueError as e:
    if 'PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH' in str(e):
        sys.exit('Fix: set PGVECTOR_USE_HALFVEC=true or lower the dimension')
    raise

Prevention

When adopting embedding models above 2000 dims, set PGVECTOR_USE_HALFVEC=true in the same change
Check the pgvector extension version supports halfvec (>=0.7) before enabling it

When it happens

Trigger: Setting VECTOR_DB=pgvector with PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH > 2000 (e.g. 3072 or 4096 for large embedding models) while PGVECTOR_USE_HALFVEC is unset/false.

Common situations: Switching embeddings to high-dimensional models (OpenAI text-embedding-3-large at 3072, or 4096-dim models) without adjusting vector storage type.

Related errors

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