spring-projects/spring-ai · error · IllegalArgumentException

Table name should only contain alphanumeric characters and…

Error message

Table name should only contain alphanumeric characters and underscores

What it means

validateNames also rejects table names that are not purely alphanumeric with underscores, for the same injection/quoting safety reasons as the schema name check. It runs before any SQL is issued against the table.

Solutions

Rename the table to only alphanumerics/underscores (e.g. vector_store).
Sanitize the configured table name before passing it to the builder.
Check the vectorStoreTableName config property for stray quotes or whitespace.

Example fix

// before
PgVectorStore.builder(jdbcTemplate, embeddingModel)
    .vectorTableName("vector-store").build();
// after
PgVectorStore.builder(jdbcTemplate, embeddingModel)
    .vectorTableName("vector_store").build();

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try {
    PgVectorStore store = builder.build();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Table name")) {
        throw new ConfigurationException("Fix vectorStoreTableName property", e);
    }
    throw e;
}

Prevention

Use snake_case table names (e.g. vector_store).
Strip hyphens/whitespace from names generated from service or app names.
Add a startup config validation bean that checks both schema and table names.

When it happens

Trigger: Building PgVectorStore with a table name containing hyphens, dots, spaces, or quotes (e.g. "vector-store") while schema validation is enabled (validateTableSchema -> validateNames).

Common situations: Table name taken from a kebab-case config key or Docker/service name; table auto-named from an app name with dashes; tenant-per-table naming schemes with separators.

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/c63242d3f6dcdebf. Report an issue: GitHub.

Appendix: source

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

	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()) {
				logger.info("Validating PGVectorStore schema for table: " + tableName + " in schema: " + schemaName);
			}

			List<String> expectedColumns = new ArrayList<>();

View on GitHub (pinned to 98a7beda4f)