spring-projects/spring-ai · error · IllegalStateException

Table does not exist in schema

Error message

Table  does not exist in schema

What it means

validateTableSchema checks information_schema/pg_catalog for the configured table and throws IllegalStateException when the table does not exist in the configured schema. This happens during store initialization when schema validation is enabled and create-if-missing is off.

Solutions

  1. Enable schema initialization: PgVectorStore.builder(...).initializeSchema(true) or set spring.ai.vectorstore.pgvector.initialize-schema=true.
  2. Run the vector_store DDL manually in the configured schema.
  3. Verify schema and table names match the actual PostgreSQL objects (SELECT from information_schema.tables).
  4. Confirm the JDBC connection points at the intended database.

Example fix

// before
PgVectorStore.builder(jdbcTemplate, embeddingModel).initializeSchema(false).build();
// after
PgVectorStore.builder(jdbcTemplate, embeddingModel).initializeSchema(true).build();
Defensive patterns

Strategy: validation

Validate before calling

Integer n = jdbcTemplate.queryForObject(
    "SELECT count(*) FROM information_schema.tables WHERE table_schema=? AND table_name=?",
    Integer.class, schemaName, tableName);
if (n == null || n == 0) {
    throw new IllegalStateException("Run DDL or set initializeSchema=true first");
}

Try / catch

try {
    vectorStore.similaritySearch(request);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("does not exist in schema")) {
        // run DDL or rebuild store with initializeSchema(true)
    } else { throw e; }
}

Prevention

When it happens

Trigger: PgVectorStore initialized with schema validation (validateTableSchema) while the target table was never created — e.g. wrong table name, wrong schema (search_path), or initializeSchema=false against an empty database.

Common situations: Fresh environment/database where DDL was never run; initializeSchema disabled but the table expected to pre-exist; connecting to the wrong database or schema; typo in schema-name/table-name properties.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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

Appendix: source

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

	}

	void validateNames(String schemaName, String tableName) {
		if (!isValidNameForDatabaseObject(schemaName)) {
			throw new IllegalArgumentException(
					"Schema name should only contain alphanumeric characters and underscores");
		}
		if (!isValidNameForDatabaseObject(tableName)) {
			throw new IllegalArgumentException(
					"Table name should only contain alphanumeric characters and underscores");
		}
	}

	void validateTableSchema(String schemaName, String tableName, int dimensions) {

		validateNames(schemaName, tableName);

		if (!isTableExists(schemaName, tableName)) {
			throw new IllegalStateException("Table " + tableName + " does not exist in schema " + schemaName);
		}

		try {
			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,

View on GitHub (pinned to 98a7beda4f)