spring-projects/spring-ai · error · IllegalStateException

Error while validating table schema, Table does not exist…

Error message

Error while validating table schema, Table  does not exist in schema

What it means

After confirming table existence, validateTableSchema queries information_schema.columns for the table's columns; an empty result triggers this IllegalStateException. This indicates the table vanished, the schema/table parameters don't match (e.g. case sensitivity or wrong schema), or permissions hide the columns.

Solutions

Check information_schema.columns for the exact table_schema/table_name values and align your configuration.
Use lowercase, unquoted identifiers for schema and table in configuration.
Re-run initialization (initializeSchema=true) to recreate a dropped table.
Grant the connecting role USAGE/SELECT on the schema.

Example fix

// before
.schema("MySchema") // PostgreSQL folds to my_schema; mismatch can yield empty columns
// after
.schema("my_schema")

Defensive patterns

Strategy: validation

Validate before calling

int cols = jdbcTemplate.queryForObject(
    "SELECT count(*) FROM information_schema.columns WHERE table_schema=? AND table_name=?",
    Integer.class, schemaName, tableName);
if (cols == 0) {
    throw new IllegalStateException("No columns visible for " + schemaName + "." + tableName + " — check identifiers/permissions");
}

Try / catch

try {
    validate(schemaName, tableName, dims);
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Error while validating table schema")) {
        // verify identifier case and schema USAGE grants
    } else { throw e; }
}

Prevention

Use lowercase unquoted PostgreSQL identifiers everywhere.
Avoid dropping/recreating the table while the app starts.
Grant the app role USAGE and SELECT on the schema.

When it happens

Trigger: information_schema.columns returns no rows for (schemaName, tableName) despite isTableExists succeeding — schema name case mismatch, table dropped concurrently, or querying the wrong schema.

Common situations: Mixed-case or quoted identifiers in PostgreSQL that information_schema stores lowercase; concurrent migrations dropping/recreating the table between the two checks; role without USAGE on the schema.

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

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

Appendix: source

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

			if (logger.isInfoEnabled()) {
				logger.info("Validating PGVectorStore schema for table: " + tableName + " in schema: " + schemaName);
			}

			List<String> expectedColumns = new ArrayList<>();
			expectedColumns.add("id");
			expectedColumns.add("content");
			expectedColumns.add("metadata");
			expectedColumns.add("embedding");

			// Query to check if the table exists with the required fields and types
			// Include the schema name in the query to target the correct table
			String query = "SELECT column_name, data_type FROM information_schema.columns "
					+ "WHERE table_schema = ? AND table_name = ?";
			List<Map<String, @Nullable Object>> columns = this.jdbcTemplate.queryForList(query,
					new Object[] { schemaName, tableName });

			if (columns.isEmpty()) {
				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);

View on GitHub (pinned to 98a7beda4f)