What causes "Template cannot be null" in alibaba/spring-ai-alibaba?

Pass a non-null template string to template(...)

alibaba/spring-ai-alibaba · error · IllegalArgumentException

Template cannot be null

Error message

Template cannot be null

What it means

TemplateTransformNode.Builder.template(String) rejects null templates with IllegalArgumentException('Template cannot be null'). A null template would make the node's text transformation impossible, so it is validated eagerly at builder time.

Solutions

Pass a non-null template string to template(...)
Verify the config/property source actually provides the template value
Add a null/blank check with a clear message before building in caller code

Example fix

// before
builder.template(config.get("template")); // may be null
// after
String tpl = config.get("template");
if (tpl == null) { throw new IllegalStateException("template config missing"); }
builder.template(tpl);

Defensive patterns

Strategy: validation

Validate before calling

if (tpl == null || tpl.isBlank()) { throw new IllegalStateException("template must be provided"); }
builder.template(tpl);

Type guard

static boolean hasTemplate(Map<String,String> cfg) { return StringUtils.hasText(cfg.get("template")); }

Try / catch

try { node = builder.template(tpl)...build(); } catch (IllegalArgumentException e) { log.error("template null", e); }

Prevention

Load templates from config with explicit defaults
Assert template presence at application startup
Avoid Map.get results passed directly into builders without null checks

When it happens

Trigger: Calling builder.template(null) directly, or passing a variable/method result that resolves to null (e.g. missing config property or unreturned map lookup).

Common situations: Template loaded from config/properties that was not set; Map.get("template") returning null; refactoring that renamed the template field.

Related errors

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

Appendix: source

Thrown at spring-boot-starters/spring-ai-alibaba-starter-builtin-nodes/src/main/java/com/alibaba/cloud/ai/graph/node/TemplateTransformNode.java:379

		return defaultValue;
	}

	public static Builder builder() {
		return new Builder();
	}

	/**
	 * Builder class for TemplateTransformNode
	 */
	public static class Builder {

		private String template;

		private String outputKey;

		public Builder template(String template) {
			if (template == null) {
				throw new IllegalArgumentException("Template cannot be null");
			}
			this.template = template;
			return this;
		}

		public Builder outputKey(String outputKey) {
			this.outputKey = outputKey;
			return this;
		}

		public TemplateTransformNode build() {
			if (template == null) {
				throw new IllegalArgumentException("Template cannot be null");
			}
			return new TemplateTransformNode(template, outputKey);
		}

	}

View on GitHub (pinned to f82da0b50f)