spring-projects/spring-ai · error · IllegalStateException

Missing fields {expectedColumns}

Error message

Missing fields {expectedColumns}

What it means

At the end of validateTableSchema, the validator compares the table's actual columns with the expected id/content/metadata/embedding fields and throws 'Missing fields <expectedColumns>' if any expected columns are absent from the table. This catches tables created with an older or wrong schema that is incompatible with the vector store.

Source

Thrown at vector-stores/spring-ai-mariadb-store/src/main/java/org/springframework/ai/vectorstore/mariadb/MariaDBSchemaValidator.java:127

			// Check each column against expected fields
			List<String> availableColumns = new ArrayList<>();
			for (Map<String, Object> column : columns) {
				String columnName = (String) column.get("COLUMN_NAME");
				Assert.state(columnName != null, "COLUMN_NAME result should not be null");
				columnName = validateAndEnquoteIdentifier(columnName, false);
				availableColumns.add(columnName);
			}

			// TODO ensure id is a primary key for batch update

			expectedColumns.removeAll(availableColumns);

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

		}
		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. Verify that the table exists with the appropriate structure. If it does not"
						+ " exist, create it using a SQL command similar to the following:\n"
						+ String.format("""
								  CREATE TABLE IF NOT EXISTS %s (
										%s UUID NOT NULL DEFAULT uuid() PRIMARY KEY,
										%s TEXT,
										%s JSON,
										%s VECTOR(%d) NOT NULL,
										VECTOR INDEX (%s)
								) ENGINE=InnoDB""", schemaName == null ? tableName : schemaName + "." + tableName,

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Drop and recreate the table (or let initialize-schema=true create it) so all expected columns exist.
2. ALTER TABLE to add the missing columns with correct types (VECTOR for the embedding column).
3. Align configured field names (idFieldName/contentFieldName/metadataFieldName/embeddingFieldName) with the actual table columns.
4. Back up data, then run the schema migration for the new spring-ai version.

Example fix

// before
CREATE TABLE vector_store (id VARCHAR(36), content TEXT);
// after
CREATE TABLE vector_store (id VARCHAR(36), content TEXT, metadata JSON, embedding VECTOR(1536));

Set<String> expected = Set.of("id", "content", "metadata", "embedding");
Set<String> actual = new HashSet<>(jdbc.queryForList(
    "SELECT COLUMN_NAME FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA=? AND TABLE_NAME=?",
    String.class, schema, table));
Set<String> missing = new HashSet<>(expected); missing.removeAll(actual);
if (!missing.isEmpty()) throw new IllegalStateException("Missing fields " + missing);

try {
    vectorStore = new MariaDBVectorStore(...);
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Missing fields")) {
        // run ALTER TABLE / recreate schema before retrying init
    }
}

When it happens

Trigger: Initializing MariaDBVectorStore against a pre-existing table whose columns don't include all of id, content, metadata, embedding (or custom configured field names), or a table created with different embedding dimension column types.

Common situations: Upgrading spring-ai versions where expected schema changed; hand-created table with missing columns; field-name config (id-field-name etc.) not matching actual columns; migration scripts that renamed columns.

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

• Table '%s' does not exist in schema '%s'
• Error while validating table schema, Table {tableName} does
• Not supported expression type: {expressionType}
• Failed to delete documents by filter
• Unknown message type:

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