{"record":{"id":"7c6a9b7b9632e577","repo":"spring-projects/spring-ai","slug":"missing-fields-expectedcolumns","errorCode":null,"errorMessage":"Missing fields {expectedColumns}","messagePattern":"Missing fields (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"vector-stores/spring-ai-mariadb-store/src/main/java/org/springframework/ai/vectorstore/mariadb/MariaDBSchemaValidator.java","lineNumber":127,"sourceCode":"\n\t\t\t// Check each column against expected fields\n\t\t\tList<String> availableColumns = new ArrayList<>();\n\t\t\tfor (Map<String, Object> column : columns) {\n\t\t\t\tString columnName = (String) column.get(\"COLUMN_NAME\");\n\t\t\t\tAssert.state(columnName != null, \"COLUMN_NAME result should not be null\");\n\t\t\t\tcolumnName = validateAndEnquoteIdentifier(columnName, false);\n\t\t\t\tavailableColumns.add(columnName);\n\t\t\t}\n\n\t\t\t// TODO ensure id is a primary key for batch update\n\n\t\t\texpectedColumns.removeAll(availableColumns);\n\n\t\t\tif (expectedColumns.isEmpty()) {\n\t\t\t\tlogger.info(\"MariaDB VectorStore schema validation successful\");\n\t\t\t}\n\t\t\telse {\n\t\t\t\tthrow new IllegalStateException(\"Missing fields \" + expectedColumns);\n\t\t\t}\n\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\tlogger.error(\"Failed to operate with the specified table in the database. To resolve this issue,\"\n\t\t\t\t\t\t+ \" please ensure the following steps are completed:\\n\"\n\t\t\t\t\t\t+ \"1. Verify that the table exists with the appropriate structure. If it does not\"\n\t\t\t\t\t\t+ \" exist, create it using a SQL command similar to the following:\\n\"\n\t\t\t\t\t\t+ String.format(\"\"\"\n\t\t\t\t\t\t\t\t  CREATE TABLE IF NOT EXISTS %s (\n\t\t\t\t\t\t\t\t\t\t%s UUID NOT NULL DEFAULT uuid() PRIMARY KEY,\n\t\t\t\t\t\t\t\t\t\t%s TEXT,\n\t\t\t\t\t\t\t\t\t\t%s JSON,\n\t\t\t\t\t\t\t\t\t\t%s VECTOR(%d) NOT NULL,\n\t\t\t\t\t\t\t\t\t\tVECTOR INDEX (%s)\n\t\t\t\t\t\t\t\t) ENGINE=InnoDB\"\"\", schemaName == null ? tableName : schemaName + \".\" + tableName,","sourceCodeStart":109,"sourceCodeEnd":145,"githubUrl":"https://github.com/spring-projects/spring-ai/blob/98a7beda4f29d80a71c5837eb4053b03a93a46f7/vector-stores/spring-ai-mariadb-store/src/main/java/org/springframework/ai/vectorstore/mariadb/MariaDBSchemaValidator.java#L109-L145","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Drop and recreate the table (or let initialize-schema=true create it) so all expected columns exist.","ALTER TABLE to add the missing columns with correct types (VECTOR for the embedding column).","Align configured field names (idFieldName/contentFieldName/metadataFieldName/embeddingFieldName) with the actual table columns.","Back up data, then run the schema migration for the new spring-ai version."],"exampleFix":"// before\nCREATE TABLE vector_store (id VARCHAR(36), content TEXT);\n// after\nCREATE TABLE vector_store (id VARCHAR(36), content TEXT, metadata JSON, embedding VECTOR(1536));","handlingStrategy":"validation","validationCode":"Set<String> expected = Set.of(\"id\", \"content\", \"metadata\", \"embedding\");\nSet<String> actual = new HashSet<>(jdbc.queryForList(\n    \"SELECT COLUMN_NAME FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA=? AND TABLE_NAME=?\",\n    String.class, schema, table));\nSet<String> missing = new HashSet<>(expected); missing.removeAll(actual);\nif (!missing.isEmpty()) throw new IllegalStateException(\"Missing fields \" + missing);","typeGuard":null,"tryCatchPattern":"try {\n    vectorStore = new MariaDBVectorStore(...);\n} catch (IllegalStateException e) {\n    if (e.getMessage().startsWith(\"Missing fields\")) {\n        // run ALTER TABLE / recreate schema before retrying init\n    }\n}","preventionTips":["Always let the library create the table (initialize-schema=true) rather than hand-writing DDL.","Keep schema migrations in sync with spring-ai version upgrades.","Match configured field names to actual columns in configuration review.","Smoke-test store init in CI against a real MariaDB with VECTOR support."],"tags":["mariadb","schema-validation","vector-store","columns"],"backgroundTag":"schema-validation-failed","analyzedSha":"98a7beda4f29d80a71c5837eb4053b03a93a46f7","analyzedAt":"2026-09-11T14:15:49.441Z","contentChangedAt":"2026-09-11T14:15:49.441Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}