spring-projects/spring-ai · error · IllegalStateException

Missing fields

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.

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

• Error while validating table schema, Table
• Table ' ' does not exist in schema
• Failed to delete documents by filter
• Not supported expression type
• Bad Request

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

Appendix: 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)