alibaba/spring-ai-alibaba · error · PIIDetectionException

Detected %d instance(s) of %s in text content

Error message

Detected %d instance(s) of %s in text content

What it means

PIIDetectionHook.afterModel() inspects model output text for the configured PII type. When matches are found and RedactionStrategy is BLOCK, it throws PIIDetectionException ("Detected N instance(s) of TYPE in text content") to stop the PII from propagating; the exception carries the PII type and match details.

Source

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

			return new AgentCommand(previousMessages);
		}

		String content = aiMessage.getText();

		if (content == null || content.isEmpty()) {
			return new AgentCommand(previousMessages);
		}

		// Detect PII
		ProcessResult result = processText(content);

		if (!result.hasMatches) {
			return new AgentCommand(previousMessages);
		}

		// Apply strategy
		if (result.hasMatches && strategy == RedactionStrategy.BLOCK) {
			throw new PIIDetectionException(piiType.name(), result.matches);
		}

		if (result.redactedText.equals(content)) {
			return new AgentCommand(previousMessages);
		}

		// Create updated message
		AssistantMessage updatedMessage = AssistantMessage.builder()
			.content(result.redactedText)
			.properties(aiMessage.getMetadata())
			.toolCalls(aiMessage.getToolCalls())
			.media(aiMessage.getMedia())
			.build();

		List<Message> updatedMessages = new ArrayList<>(previousMessages);
		updatedMessages.set(lastIndex, updatedMessage);

		return new AgentCommand(updatedMessages, UpdatePolicy.REPLACE);

View on GitHub (pinned to f82da0b50f)

Solutions

1. Catch PIIDetectionException and handle per compliance policy (log, notify, retry with sanitization instructions).
2. Switch strategy to RedactionStrategy.REDACT so matched PII is masked instead of blocking the response.
3. Instruct/tune the model not to emit PII, or post-process prompts to remove PII from inputs that get echoed back.
4. If matches are false positives, adjust the detector or PII type configuration.

Example fix

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

// pre-screen model output if you have access to it
// (with BLOCK strategy the hook itself is the gate)
boolean containsPii = PIIDetectors.emailDetector().detect(outputText).size() > 0;

try {
    result = agent.invoke(inputs);
} catch (PIIDetectionException e) {
    log.warn("PII blocked: type={}, matches={}", e.getPiiType(), e.getMatches());
    // retry with REDACT strategy or sanitization prompt
}

When it happens

Trigger: Configuring PIIDetectionHook with strategy RedactionStrategy.BLOCK and the model's afterModel output containing text matching the PII detector (e.g. email addresses, phone numbers, IPs).

Common situations: LLM echoing back user-supplied PII in its answer; summarization or RAG answers embedding contact details from documents; strict compliance pipelines that intentionally block rather than redact.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• No default detector for PII type: ${type}
• piiType must be specified
• Elastic search index name must be provided
• Param Not Support Object
• Param Not Support Array<Object>

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