spring-projects/spring-ai · error · IllegalStateException

Missing fields

Error message

Missing fields 

What it means

validateTableSchema compares the table's actual columns against the expected vector_store column set (id, content, metadata, embedding, and related columns). If any expected columns are absent from the table, it throws IllegalStateException listing the missing fields. This catches tables created by an older version of the library or hand-made with a different layout.

Solutions

1. Drop/recreate or ALTER the table to match the current expected schema, ideally by enabling initializeSchema=true against a fresh table.
2. Add the missing columns via ALTER TABLE vector_store ADD COLUMN ... per the listed fields.
3. Compare your DDL against the CREATE_VECTOR_STORE_SQL in PgVectorStore for your library version.
4. Pin the Spring AI version so schema and code stay consistent.

Example fix

// before
CREATE TABLE vector_store (id uuid PRIMARY KEY, content text);
// after
ALTER TABLE vector_store ADD COLUMN metadata json;
ALTER TABLE vector_store ADD COLUMN embedding vector(1536);

Set<String> expected = Set.of("id", "content", "metadata", "embedding");
Set<String> actual = jdbcTemplate.queryForList(
    "SELECT column_name FROM information_schema.columns WHERE table_schema=? AND table_name=?",
    String.class, schemaName, tableName).stream().collect(Collectors.toSet());
Set<String> missing = new HashSet<>(expected); missing.removeAll(actual);
if (!missing.isEmpty()) {
    throw new IllegalStateException("Missing columns: " + missing);
}

try {
    vectorStore.afterPropertiesSet();
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Missing fields")) {
        // ALTER TABLE to add missing columns or recreate
    } else { throw e; }
}

When it happens

Trigger: Pointing PgVectorStore schema validation at a table created by an earlier Spring AI version or by a custom DDL that lacks one of the required columns (e.g. missing metadata or index columns).

Common situations: Upgrading spring-ai after the vector_store schema changed; a table created by another framework with a similar name; partially applied migrations.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Error while validating table schema, Table does not exist…
• Schema name should only contain alphanumeric characters and…
• Table does not exist in schema
• Table name should only contain alphanumeric characters and…
• Actual vector dimensions is , required vector dimensions is

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

Appendix: source

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

				throw new IllegalStateException("Error while validating table schema, Table " + tableName
						+ " does not exist in schema " + schemaName);
			}

			// Check each column against expected fields
			List<String> availableColumns = new ArrayList<>();
			for (Map<String, @Nullable Object> column : columns) {
				String columnName = (String) column.get("column_name");
				availableColumns.add(columnName);

			}

			expectedColumns.removeAll(availableColumns);

			if (expectedColumns.isEmpty()) {
				logger.info("PG VectorStore schema validation successful");
			}
			else {
				throw new IllegalStateException("Missing fields " + expectedColumns);
			}

			// Query the actual dimensions
			query = """
					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

View on GitHub (pinned to 98a7beda4f)