{"record":{"id":"b72d6f1a72b72fd1","repo":"open-webui/open-webui","slug":"pgvector-initialize-max-vector-length-is-set-to-p","errorCode":null,"errorMessage":"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.","messagePattern":"PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH is set to (.+?), 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\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"critical","filePath":"backend/open_webui/config.py","lineNumber":648,"sourceCode":"ELASTICSEARCH_CA_CERTS = os.getenv('ELASTICSEARCH_CA_CERTS', None)\nELASTICSEARCH_API_KEY = os.getenv('ELASTICSEARCH_API_KEY', None)\nELASTICSEARCH_USERNAME = os.getenv('ELASTICSEARCH_USERNAME', None)\nELASTICSEARCH_PASSWORD = os.getenv('ELASTICSEARCH_PASSWORD', None)\nELASTICSEARCH_CLOUD_ID = os.getenv('ELASTICSEARCH_CLOUD_ID', None)\nSSL_ASSERT_FINGERPRINT = os.getenv('SSL_ASSERT_FINGERPRINT', None)\nELASTICSEARCH_INDEX_PREFIX = os.getenv('ELASTICSEARCH_INDEX_PREFIX', 'open_webui_collections')\n# Pgvector\nPGVECTOR_DB_URL = os.getenv('PGVECTOR_DB_URL', DATABASE_URL)\nif VECTOR_DB == 'pgvector' and not PGVECTOR_DB_URL.startswith('postgres'):\n    raise ValueError(\n        'Pgvector requires setting PGVECTOR_DB_URL or using Postgres with vector extension as the primary database.'\n    )\nPGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH = int(os.getenv('PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH', '1536'))\n\nPGVECTOR_USE_HALFVEC = os.getenv('PGVECTOR_USE_HALFVEC', 'false').lower() == 'true'\n\nif PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH > 2000 and not PGVECTOR_USE_HALFVEC:\n    raise ValueError(\n        'PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH is set to '\n        f'{PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH}, which exceeds the 2000 dimension limit of the '\n        \"'vector' type. Set PGVECTOR_USE_HALFVEC=true to enable the 'halfvec' \"\n        'type required for high-dimensional embeddings.'\n    )\n\nPGVECTOR_CREATE_EXTENSION = os.getenv('PGVECTOR_CREATE_EXTENSION', 'true').lower() == 'true'\nPGVECTOR_PGCRYPTO = os.getenv('PGVECTOR_PGCRYPTO', 'false').lower() == 'true'\nPGVECTOR_PGCRYPTO_KEY = os.getenv('PGVECTOR_PGCRYPTO_KEY', None)\nif PGVECTOR_PGCRYPTO and not PGVECTOR_PGCRYPTO_KEY:\n    raise ValueError('PGVECTOR_PGCRYPTO is enabled but PGVECTOR_PGCRYPTO_KEY is not set. Please provide a valid key.')\n\n\nPGVECTOR_POOL_SIZE = os.getenv('PGVECTOR_POOL_SIZE', None)\n\nif PGVECTOR_POOL_SIZE != None:\n    try:\n        PGVECTOR_POOL_SIZE = int(PGVECTOR_POOL_SIZE)","sourceCodeStart":630,"sourceCodeEnd":666,"githubUrl":"https://github.com/open-webui/open-webui/blob/01f4282f1ffe0d6212f58d3afbeae21fffd0c4be/backend/open_webui/config.py#L630-L666","documentation":"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.","triggerScenarios":"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.","commonSituations":"Switching embeddings to high-dimensional models (OpenAI text-embedding-3-large at 3072, or 4096-dim models) without adjusting vector storage type.","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)"],"exampleFix":"# before\nVECTOR_DB=pgvector\nPGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH=3072  # raises\n# after\nVECTOR_DB=pgvector\nPGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH=3072\nPGVECTOR_USE_HALFVEC=true","handlingStrategy":"validation","validationCode":"dim = int(os.getenv('PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH', '1536'))\nhalf = os.getenv('PGVECTOR_USE_HALFVEC', 'false').lower() == 'true'\nif os.getenv('VECTOR_DB') == 'pgvector' and dim > 2000 and not half:\n    raise SystemExit('Set PGVECTOR_USE_HALFVEC=true for dims > 2000')","typeGuard":null,"tryCatchPattern":"try:\n    import open_webui.config\nexcept ValueError as e:\n    if 'PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH' in str(e):\n        sys.exit('Fix: set PGVECTOR_USE_HALFVEC=true or lower the dimension')\n    raise","preventionTips":["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"],"tags":["configuration","pgvector","embeddings","vector-db","startup","env"],"backgroundTag":null,"analyzedSha":"01f4282f1ffe0d6212f58d3afbeae21fffd0c4be","analyzedAt":"2026-08-14T18:25:22.715Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}