alibaba/spring-ai-alibaba · error · IllegalArgumentException

'%s' cannot be blank

Error message

'%s' cannot be blank

What it means

Builder.requireNotBlank rejects null or whitespace-only required string settings (database name, user, etc.), formatting the field name into the message. It is builder-time validation ensuring mandatory connection parameters are present and non-empty.

Source

Thrown at spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/checkpoint/savers/postgresql/PostgresSaver.java:727

		/**
		 * @deprecated Use {@link #createOption(CreateOption)} instead.
		 * Sets whether to drop tables before creating them.
		 * @param dropTablesFirst true to drop tables first
		 * @return this builder
		 */
		@Deprecated
		public Builder dropTablesFirst(boolean dropTablesFirst) {
			this.dropTablesFirst = dropTablesFirst;
			// Convert to CreateOption for backward compatibility
			if (dropTablesFirst && this.createOption != CreateOption.CREATE_NONE) {
				this.createOption = CreateOption.CREATE_OR_REPLACE;
			}
			return this;
		}

		private String requireNotBlank(String value, String name) {
			if (requireNonNull(value, format("'%s' cannot be null", name)).isBlank()) {
				throw new IllegalArgumentException(format("'%s' cannot be blank", name));
			}
			return value;
		}

		public PostgresSaver build() {
			if (stateSerializer == null) {
				log.info("No StateSerializer for saver provided, using default SpringAiJacksonStateSerializer, please make sure saver uses the same serializer of the graph.");
				this.stateSerializer = StateGraph.DEFAULT_JACKSON_SERIALIZER;
			}

			// If datasource is already set (e.g., for testing), use it directly
			if (datasource == null) {
				if (port == null || port <= 0) {
					throw new IllegalArgumentException("port must be greater than 0");
				}
				var ds = new PGSimpleDataSource();
				ds.setDatabaseName(requireNotBlank(database, "database"));
				ds.setUser(requireNotBlank(user, "user"));

View on GitHub (pinned to f82da0b50f)

Solutions

1. Provide the required non-blank value in the builder (database(...), user(...)).
2. Check the originating config file/env var is set and not just whitespace; trim before passing.
3. Add startup validation of your own configuration before building the saver to fail with a clearer message.

Example fix

// before
String user = env.get("DB_USER"); // may be ""
builder.user(user);
// after
String user = env.get("DB_USER");
if (user == null || user.isBlank()) throw new IllegalStateException("DB_USER must be set");
builder.user(user.trim());

static void requireConfigValue(String v, String name) {
    if (v == null || v.isBlank()) throw new IllegalStateException(name + " must be set and non-blank");
}
// usage: requireConfigValue(env.get("DB_USER"), "DB_USER");

try { builder.user(raw); } catch (IllegalArgumentException e) { throw new IllegalStateException("Check DB user config: " + e.getMessage(), e); }

When it happens

Trigger: Calling database(null), user(""), or user(" ") on PostgresSaver.Builder, typically from blank config values loaded from environment variables or application.yml.

Common situations: Unset env var interpolated as empty string in YAML; placeholder not replaced (${DB_USER} unresolved); trimming issues where a field contains only spaces.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• port must be greater than 0
• SkillRegistry must be provided. Use FileSystemSkillRegistry.
• At least one limit must be specified (threadLimit or runLimi
• maxCachedThreads must be greater than or equal to 0
• oss ak or sk should be set.

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/246f8504431e8830. Report an issue: GitHub.