spring-projects/spring-ai · error · IllegalArgumentException

Schema name should only contain alphanumeric characters and…

Error message

Schema name should only contain alphanumeric characters and underscores

What it means

PgVectorSchemaValidator.validateNames rejects schema names that are not purely alphanumeric with underscores. This guards against SQL injection and quoting problems when the schema name is embedded in identifiers and DDL queries.

Solutions

Rename the schema in PostgreSQL to contain only alphanumerics and underscores (e.g. my_schema).
Sanitize the configured schema name before passing it to the builder.
Replace disallowed characters: schemaName.replaceAll("[^A-Za-z0-9_]", "_").

Example fix

// before
PgVectorStore.builder(jdbcTemplate, embeddingModel)
    .schema("my-schema").build();
// after
PgVectorStore.builder(jdbcTemplate, embeddingModel)
    .schema("my_schema").build();

Defensive patterns

Strategy: validation

Validate before calling

Objects.requireNonNull(schemaName, "schema");
if (!schemaName.matches("[A-Za-z0-9_]+")) {
    throw new IllegalArgumentException("Schema name must be alphanumeric/underscore: " + schemaName);
}

Try / catch

try {
    PgVectorStore store = builder.build();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Schema name")) {
        throw new ConfigurationException("Fix spring.ai.vectorstore.pgvector.schema-name", e);
    }
    throw e;
}

Prevention

Validate schema-name config at application startup.
Keep schema names lowercase snake_case in all environments.
Never derive schema names directly from user or tenant input without sanitizing.

When it happens

Trigger: Constructing PgVectorStore (or PgVectorStore.builder) with a schema name containing hyphens, dots, spaces, quotes, or other non [A-Za-z0-9_] characters, with initialize-schema/validation enabled.

Common situations: Config value spring.ai.vectorstore.pgvector.schema-name copied from a connection string or environment-specific name like "my-schema" or "dev schema"; schema names derived from tenant IDs with dashes.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

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

Appendix: source

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

		return true;

	}

	boolean isTableExists(String schemaName, String tableName) {
		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, tableName);
			return true;
		}
		catch (DataAccessException e) {
			return false;
		}
	}

	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()) {

View on GitHub (pinned to 98a7beda4f)