spring-projects/spring-ai · error · IllegalStateException

Actual vector dimensions is , required vector dimensions is

Error message

Actual vector dimensions is , required vector dimensions is

What it means

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.

Solutions

  1. Drop and recreate the table with vector column dimension matching the embedding model (or let initializeSchema=true recreate it).
  2. Set PgVectorStore.builder(...).dimensions(modelDimensions) to match the actual column size.
  3. Migrate data to a new table with the correct dimension before switching models.
  4. Verify with: SELECT a.atttypmod FROM pg_attribute a WHERE attname='embedding'.

Example fix

// before
embedding vector(1536)  -- but model outputs 384
// after
DROP TABLE vector_store;
CREATE TABLE vector_store (... embedding vector(384) ...);
Defensive patterns

Strategy: validation

Validate before calling

int modelDims = embeddingModel.dimensions();
Integer colDims = jdbcTemplate.queryForObject(
    "SELECT atttypmod FROM pg_attribute WHERE attrelid = ?::regclass AND attname = 'embedding'",
    Integer.class, schemaName + "." + tableName);
if (colDims == null || colDims != modelDims) {
    throw new IllegalStateException("Recreate table with vector(" + modelDims + ")");
}

Try / catch

try {
    vectorStore.afterPropertiesSet();
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Actual vector dimensions")) {
        // recreate table with correct vector(n) or adjust dimensions config
    } else { throw e; }
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Tensor shape mismatch errors ("must have shape", "expected shape ... got ..."): when tensor dimensions disagree with what an op or layer was told to expect — this error's family across 6 libraries.

Related errors

AI-assisted analysis of spring-projects/spring-ai@98a7beda4f (2026-09-11). Data as JSON: /api/errors/ae8aeabd1dcc501f. Report an issue: GitHub.

Appendix: source

Thrown at vector-stores/spring-ai-pgvector-store/src/main/java/org/springframework/ai/vectorstore/pgvector/PgVectorSchemaValidator.java:161

					SELECT
						a.atttypmod
					FROM
						pg_attribute a
					JOIN
						pg_class c ON a.attrelid = c.oid
					JOIN
						pg_namespace n ON c.relnamespace = n.oid
					WHERE
						n.nspname = ?
						AND c.relname = ?
						AND a.attname = ?
						AND a.attnum > 0
						AND NOT a.attisdropped
					""";
			Integer actualDimensions = this.jdbcTemplate.queryForObject(query, Integer.class, schemaName, tableName,
					"embedding");
			if (actualDimensions == null || actualDimensions != dimensions) {
				throw new IllegalStateException("Actual vector dimensions is " + actualDimensions
						+ ", required vector dimensions is " + dimensions);
			}
		}
		catch (DataAccessException | IllegalStateException e) {
			if (logger.isErrorEnabled()) {
				logger.error("Error while validating table schema: " + e.getMessage());
			}
			logger
				.error("Failed to operate with the specified table in the database. To resolve this issue, please ensure the following steps are completed:\n"
						+ "1. Ensure the necessary PostgreSQL extensions are enabled. Run the following SQL commands:\n"
						+ "   CREATE EXTENSION IF NOT EXISTS vector;\n" + "   CREATE EXTENSION IF NOT EXISTS hstore;\n"
						+ "   CREATE EXTENSION IF NOT EXISTS \"uuid-ossp\";\n"
						+ "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"
						+ String.format("   CREATE TABLE IF NOT EXISTS %s (\n"
								+ "       id uuid DEFAULT uuid_generate_v4() PRIMARY KEY,\n" + "       content text,\n"
								+ "       metadata json,\n"
								+ "       embedding vector(embedding_dimensions)  // Replace 'embedding_dimensions' with your specific value\n"
								+ "   );\n", schemaName + "." + tableName)

View on GitHub (pinned to 98a7beda4f)