alibaba/spring-ai-alibaba · error · IllegalArgumentException

piiType must be specified

Error message

piiType must be specified

What it means

PIIDetectionHook.Builder.build() requires a piiType to be set; without one the hook would not know what to detect, so it throws IllegalArgumentException. This is a fail-fast validation at hook construction.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/hook/pii/PIIDetectionHook.java:373

		public Builder applyToInput(boolean applyToInput) {
			this.applyToInput = applyToInput;
			return this;
		}

		public Builder applyToOutput(boolean applyToOutput) {
			this.applyToOutput = applyToOutput;
			return this;
		}

		public Builder applyToToolResults(boolean applyToToolResults) {
			this.applyToToolResults = applyToToolResults;
			return this;
		}

		public PIIDetectionHook build() {
			if (piiType == null) {
				throw new IllegalArgumentException("piiType must be specified");
			}
			return new PIIDetectionHook(this);
		}
	}
}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Call .piiType(PIIType.XXX) on the builder before build().
2. Validate the config value feeding the builder is non-null before constructing the hook.
3. Provide a default PII type in configuration so the field is always populated.

Example fix

// before
PIIDetectionHook hook = PIIDetectionHook.builder().strategy(RedactionStrategy.BLOCK).build();
// after
PIIDetectionHook hook = PIIDetectionHook.builder().piiType(PIIType.EMAIL).strategy(RedactionStrategy.BLOCK).build();

PIIType type = config.getPiiType();
if (type == null) {
    throw new IllegalStateException("piiType is required in configuration");
}

When it happens

Trigger: Calling PIIDetectionHook.builder()...build() without calling .piiType(...) — e.g. building from dynamic config where the type key was absent.

Common situations: Configuration file or environment missing the PII type property; copy-pasted builder code with the piiType line removed; conditional builder flows that skip setting the type.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• At least one limit must be specified (threadLimit or runLimi
• SubAgent name is required
• SubAgent description is required
• SubAgent system prompt is required
• ChatModel must be provided for LLM routing agent

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