{"record":{"id":"ae8aeabd1dcc501f","repo":"spring-projects/spring-ai","slug":"actual-vector-dimensions-is-required-vector-dime","errorCode":null,"errorMessage":"Actual vector dimensions is , required vector dimensions is ","messagePattern":"Actual vector dimensions is , required vector dimensions is ","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"vector-stores/spring-ai-pgvector-store/src/main/java/org/springframework/ai/vectorstore/pgvector/PgVectorSchemaValidator.java","lineNumber":161,"sourceCode":"\t\t\t\t\tSELECT\n\t\t\t\t\t\ta.atttypmod\n\t\t\t\t\tFROM\n\t\t\t\t\t\tpg_attribute a\n\t\t\t\t\tJOIN\n\t\t\t\t\t\tpg_class c ON a.attrelid = c.oid\n\t\t\t\t\tJOIN\n\t\t\t\t\t\tpg_namespace n ON c.relnamespace = n.oid\n\t\t\t\t\tWHERE\n\t\t\t\t\t\tn.nspname = ?\n\t\t\t\t\t\tAND c.relname = ?\n\t\t\t\t\t\tAND a.attname = ?\n\t\t\t\t\t\tAND a.attnum > 0\n\t\t\t\t\t\tAND NOT a.attisdropped\n\t\t\t\t\t\"\"\";\n\t\t\tInteger actualDimensions = this.jdbcTemplate.queryForObject(query, Integer.class, schemaName, tableName,\n\t\t\t\t\t\"embedding\");\n\t\t\tif (actualDimensions == null || actualDimensions != dimensions) {\n\t\t\t\tthrow new IllegalStateException(\"Actual vector dimensions is \" + actualDimensions\n\t\t\t\t\t\t+ \", required vector dimensions is \" + dimensions);\n\t\t\t}\n\t\t}\n\t\tcatch (DataAccessException | IllegalStateException e) {\n\t\t\tif (logger.isErrorEnabled()) {\n\t\t\t\tlogger.error(\"Error while validating table schema: \" + e.getMessage());\n\t\t\t}\n\t\t\tlogger\n\t\t\t\t.error(\"Failed to operate with the specified table in the database. To resolve this issue, please ensure the following steps are completed:\\n\"\n\t\t\t\t\t\t+ \"1. Ensure the necessary PostgreSQL extensions are enabled. Run the following SQL commands:\\n\"\n\t\t\t\t\t\t+ \"   CREATE EXTENSION IF NOT EXISTS vector;\\n\" + \"   CREATE EXTENSION IF NOT EXISTS hstore;\\n\"\n\t\t\t\t\t\t+ \"   CREATE EXTENSION IF NOT EXISTS \\\"uuid-ossp\\\";\\n\"\n\t\t\t\t\t\t+ \"2. Verify that the table exists with the appropriate structure. If it does not exist, create it using a SQL command similar to the following, replacing 'embedding_dimensions' with the appropriate size based on your vector embeddings:\\n\"\n\t\t\t\t\t\t+ String.format(\"   CREATE TABLE IF NOT EXISTS %s (\\n\"\n\t\t\t\t\t\t\t\t+ \"       id uuid DEFAULT uuid_generate_v4() PRIMARY KEY,\\n\" + \"       content text,\\n\"\n\t\t\t\t\t\t\t\t+ \"       metadata json,\\n\"\n\t\t\t\t\t\t\t\t+ \"       embedding vector(embedding_dimensions)  // Replace 'embedding_dimensions' with your specific value\\n\"\n\t\t\t\t\t\t\t\t+ \"   );\\n\", schemaName + \".\" + tableName)","sourceCodeStart":143,"sourceCodeEnd":179,"githubUrl":"https://github.com/spring-projects/spring-ai/blob/98a7beda4f29d80a71c5837eb4053b03a93a46f7/vector-stores/spring-ai-pgvector-store/src/main/java/org/springframework/ai/vectorstore/pgvector/PgVectorSchemaValidator.java#L143-L179","documentation":"validateTableSchema reads the embedding column's atttypmod to determine the vector dimensionality and throws IllegalStateException when it differs from the configured dimension (e.g. the embedding model's output size). This prevents runtime insert failures when the model's vector size does not match the pgvector column definition.","triggerScenarios":"Embedding model dimension changed (e.g. switching from OpenAI text-embedding-ada-002 (1536) to another model like 3072 or 384) while the vector(n) column was created with the old dimension; or PgVectorStore.builder(...).dimensions(N) set to a value not matching the table.","commonSituations":"Swapping embedding providers/models without recreating the table; copying a table between environments with different models; manually defining vector(384) when the model outputs 1536.","solutions":["Drop and recreate the table with vector column dimension matching the embedding model (or let initializeSchema=true recreate it).","Set PgVectorStore.builder(...).dimensions(modelDimensions) to match the actual column size.","Migrate data to a new table with the correct dimension before switching models.","Verify with: SELECT a.atttypmod FROM pg_attribute a WHERE attname='embedding'."],"exampleFix":"// before\nembedding vector(1536)  -- but model outputs 384\n// after\nDROP TABLE vector_store;\nCREATE TABLE vector_store (... embedding vector(384) ...);","handlingStrategy":"validation","validationCode":"int modelDims = embeddingModel.dimensions();\nInteger colDims = jdbcTemplate.queryForObject(\n    \"SELECT atttypmod FROM pg_attribute WHERE attrelid = ?::regclass AND attname = 'embedding'\",\n    Integer.class, schemaName + \".\" + tableName);\nif (colDims == null || colDims != modelDims) {\n    throw new IllegalStateException(\"Recreate table with vector(\" + modelDims + \")\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    vectorStore.afterPropertiesSet();\n} catch (IllegalStateException e) {\n    if (e.getMessage().startsWith(\"Actual vector dimensions\")) {\n        // recreate table with correct vector(n) or adjust dimensions config\n    } else { throw e; }\n}","preventionTips":["Derive the vector column size from embeddingModel.dimensions(), never hard-code it.","Recreate or migrate the table whenever the embedding model changes.","Record model + dimension in a migration note per environment."],"tags":["pgvector","vector-dimensions","embedding-model"],"backgroundTag":"tensor-shape-mismatch","analyzedSha":"98a7beda4f29d80a71c5837eb4053b03a93a46f7","analyzedAt":"2026-09-11T14:15:49.441Z","contentChangedAt":"2026-09-11T14:15:49.441Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}