spring-projects/spring-ai · error · IllegalArgumentException

Identifier ' ' should only contain alphanumeric characters…

Error message

Identifier '%s' should only contain alphanumeric characters and underscores

What it means

MariaDBSchemaValidator.validateAndEnquoteIdentifier validates schema/table/column identifiers before quoting them in SQL. If an identifier contains characters other than alphanumerics and underscores (after Driver.enquoteIdentifier), it throws this IllegalArgumentException to prevent SQL injection through identifier fields.

Solutions

Rename the table/schema/identifiers to contain only [A-Za-z0-9_] characters.
Create a new compliant table and copy data into it.
If the special-character name must be kept, create an underscore-only view/alias and point the store at it.

Example fix

// before
spring.ai.vectorstore.mariadb.table-name=my-vector-store
// after
spring.ai.vectorstore.mariadb.table-name=my_vector_store

Defensive patterns

Strategy: validation

Validate before calling

boolean isValidIdentifier(String s) {
    return java.util.regex.Pattern.compile("[\\p{Alnum}_]+").matcher(s).matches();
}
// assert isValidIdentifier(tableName) before configuring the store

Try / catch

try {
    new MariaDBVectorStore(...);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("should only contain alphanumeric")) {
        // fail fast with a rename hint
    }
}

Prevention

Adopt a naming convention of [a-zA-Z0-9_] for all DB identifiers.
Add config validation that rejects hyphens/dots/spaces in table/schema names at startup.
Never derive table names from untrusted user input.
Document allowed identifier format wherever vector store config is set.

When it happens

Trigger: Configuring the MariaDB store with a table name, schema name, or field name containing hyphens, dots, spaces, or other special characters — e.g. table-name: 'my-store' — triggers validation during initializeSchema/validateTableSchema.

Common situations: Copy-pasting table names with hyphens from other systems, schema names with dots, using reserved characters to try to force quoting, environment-specific naming conventions 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/ac329deb6ed1d006. Report an issue: GitHub.

Appendix: source

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

	/**
	 * Escaped identifier according to MariaDB requirement.
	 * @param identifier identifier
	 * @param alwaysQuote indicate if identifier must be quoted even if not necessary.
	 * @return return escaped identifier, quoted when necessary or indicated with
	 * alwaysQuote.
	 * @see <a href="https://mariadb.com/kb/en/library/identifier-names/">mariadb
	 * identifier name</a>
	 */
	// @Override when not supporting java 8
	public static String validateAndEnquoteIdentifier(String identifier, boolean alwaysQuote) {
		try {
			String quotedId = Driver.enquoteIdentifier(identifier, alwaysQuote);
			// force use of simple table name
			if (Pattern.compile("`?[\\p{Alnum}_]*`?").matcher(identifier).matches()) {
				return quotedId;
			}
			throw new IllegalArgumentException(String
				.format("Identifier '%s' should only contain alphanumeric characters and underscores", quotedId));
		}
		catch (SQLException e) {
			throw new IllegalArgumentException(e);
		}
	}

}

View on GitHub (pinned to 98a7beda4f)