alibaba/spring-ai-alibaba · error · IllegalArgumentException

'%s' cannot be blank

Error message

'%s' cannot be blank

What it means

Builder.requireNotBlank is the internal guard used by database() and build() for string options; it throws IllegalArgumentException("'%s' cannot be blank") when the value is null-or-blank (null yields a 'cannot be null' message via requireNonNull instead). It ensures the H2 database identifier/name is a real value before constructing the saver.

Source

Thrown at spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/checkpoint/savers/h2/H2Saver.java:566

			return this;
		}

		public Builder createOption(CreateOption createOption) {
			this.createOption = requireNonNull(createOption, "createOption cannot be null");
			return this;
		}

		public Builder maxCachedThreads(int maxCachedThreads) {
			if (maxCachedThreads < 0) {
				throw new IllegalArgumentException("maxCachedThreads must be greater than or equal to 0");
			}
			this.maxCachedThreads = maxCachedThreads;
			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 H2Saver build() {
			if (stateSerializer == null) {
				this.stateSerializer = StateGraph.DEFAULT_JACKSON_SERIALIZER;
			}
			if (dataSource == null) {
				dataSource = new DriverManagerDataSource(requireNotBlank(jdbcUrl, "jdbcUrl"), user, password);
			}
			try {
				return new H2Saver(this);
			}
			catch (SQLException ex) {
				throw new RuntimeException(ex);
			}
		}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Supply a non-blank value for the named option before calling build().
2. Validate configuration at startup: reject blank values with a clear message before reaching the builder.
3. Use Spring's @Validated/@NotBlank on config properties so the failure surfaces at context startup.

Example fix

// before: blank config value flows into builder
H2Saver.builder().database(props.db()).build(); // IllegalArgumentException
// after: validate first
if (props.db() == null || props.db().isBlank()) throw new IllegalStateException("h2 database name required");
H2Saver.builder().database(props.db()).build();

Objects.requireNonNull(db, "h2 database name required"); if (db.isBlank()) throw new IllegalArgumentException("h2 database name required");

Optional<String> nonBlank(String s) { return Optional.ofNullable(s).map(String::strip).filter(v -> !v.isEmpty()); }

try { H2Saver saver = builder.database(db).build(); }
catch (IllegalArgumentException e) { throw new IllegalStateException("invalid H2 saver config: " + e.getMessage(), e); }

When it happens

Trigger: Calling builder.database(null/""/" ") or build() with any required string option left blank — the guard fires with the option's name in the message.

Common situations: Config property for the database name missing or whitespace-only; YAML property bound to an empty string; empty env variable interpolated into the builder call.

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

• At least one fallback model must be specified
• maxAttempts must be greater than or equal to 1
• initialDelay must be greater than or equal to 0.
• maxContentLength must be positive
• maxCachedThreads must be greater than or equal to 0

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