spring-projects/spring-ai · critical · IllegalStateException

Table '%s' does not exist in schema '%s'

Error message

Table '%s' does not exist in schema '%s'

What it means

MariaDBSchemaValidator.validateTableSchema first checks that the configured vector store table exists via isTableExists. If it does not, it throws an IllegalStateException naming the missing table and schema. This fails fast during MariaDBVectorStore initialization before any query runs.

Source

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

	private boolean isTableExists(@Nullable String schemaName, String tableName) {
		// schema and table are expected to be escaped
		String sql = "SELECT 1 FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ?";
		try {
			// Query for a single integer value, if it exists, table exists
			this.jdbcTemplate.queryForObject(sql, Integer.class, (schemaName == null) ? "SCHEMA()" : schemaName,
					tableName);
			return true;
		}
		catch (DataAccessException e) {
			return false;
		}
	}

	void validateTableSchema(@Nullable String schemaName, String tableName, String idFieldName, String contentFieldName,
			String metadataFieldName, String embeddingFieldName, int embeddingDimensions) {

		if (!isTableExists(schemaName, tableName)) {
			throw new IllegalStateException(
					String.format("Table '%s' does not exist in schema '%s'", tableName, schemaName));
		}

		// ensure server support VECTORs
		try {
			// Query for a single integer value, if it exists, database support vector
			this.jdbcTemplate.queryForObject("SELECT vec_distance_euclidean(x'0000803f', x'0000803f')", Integer.class,
					schemaName, tableName);
		}
		catch (DataAccessException e) {
			if (logger.isErrorEnabled()) {
				logger.error("Error while validating database vector support " + e.getMessage());
				logger.error("""
						Failed to validate that database supports VECTOR.
						Run the following SQL commands:
						   SELECT @@version;
						And ensure that version is >= 11.7.1""");
			}

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Set initialize-schema=true (spring.ai.vectorstore.mariadb.initialize-schema) so the store creates the table automatically.
2. Manually run the store's schema creation SQL (CREATE TABLE ... VECTOR column) in the target schema.
3. Verify the configured schema and table names match what exists in MariaDB (SHOW TABLES / SELECT from INFORMATION_SCHEMA).
4. Confirm the JDBC URL connects to the intended database instance.

Example fix

// before
// application.yml: spring.ai.vectorstore.mariadb.initialize-schema: false (table missing)
// after
spring:
  ai:
    vectorstore:
      mariadb:
        initialize-schema: true

boolean tableExists(JdbcTemplate jdbc, String schema, String table) {
    Integer n = jdbc.queryForObject(
        "SELECT COUNT(*) FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_SCHEMA=? AND TABLE_NAME=?",
        Integer.class, schema, table);
    return n != null && n > 0;
}
// call before constructing the store; enable initialize-schema if false

try {
    vectorStore = new MariaDBVectorStore(...); // init validates schema
} catch (IllegalStateException e) {
    if (e.getMessage().contains("does not exist")) {
        // trigger schema creation or fail startup with clear message
    }
}

When it happens

Trigger: Initializing MariaDBVectorStore (e.g. afterPropertiesSet calls validateTableSchema) when the configured table was never created or initializeSchema is disabled, the table lives in a different schema/database, or the configured table/schema names are wrong.

Common situations: Pointing the store at a fresh database without running schema initialization, typo in spring.ai.vectorstore.mariadb.table-name or schema config, connecting to wrong database instance/environment, table dropped by 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 {tableName} does
• Missing fields {expectedColumns}
• Failed to delete documents by filter
• Failed to delete documents by filter
• Failed to delete documents by filter

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