spring-projects/spring-ai · error · IllegalStateException

SHA-256 not available

Error message

SHA-256 not available

What it means

This IllegalStateException is thrown when the JVM cannot provide a SHA-256 MessageDigest while ToolSearchToolCallingAdvisor.computeFingerprint builds a hash of the tool list (tool names, descriptions and summaries are fed into the digest and hex-encoded). SHA-256 is mandated by the Java specification to exist in every JDK, so this failure indicates a broken or non-compliant JCA provider configuration rather than normal usage.

Source

Thrown at advisors/spring-ai-tool-search-advisor/src/main/java/org/springframework/ai/chat/client/advisor/toolsearch/ToolSearchToolCallingAdvisor.java:350

	/**
	 * Computes a stable SHA-256 fingerprint for the given tool set. Tools are sorted by
	 * name so that registration order does not affect equality. Hashing avoids false
	 * cache hits that string-concatenation with delimiters can produce when names or
	 * summaries contain those delimiter characters.
	 */
	private static String computeFingerprint(List<ToolReference> toolReferences) {
		try {
			MessageDigest digest = MessageDigest.getInstance("SHA-256");
			toolReferences.stream().sorted(Comparator.comparing(ToolReference::toolName)).forEachOrdered(tr -> {
				digest.update(tr.toolName().getBytes(StandardCharsets.UTF_8));
				digest.update((byte) 0); // field separator
				digest.update(tr.summary().getBytes(StandardCharsets.UTF_8));
				digest.update((byte) 1); // entry separator
			});
			return HexFormat.of().formatHex(digest.digest());
		}
		catch (NoSuchAlgorithmException e) {
			throw new IllegalStateException("SHA-256 not available", e);
		}
	}

	// -------------------------------------------------------------------------
	// Builder
	// -------------------------------------------------------------------------

	/**
	 * Creates a new Builder instance for constructing a ToolSearchToolCallingAdvisor.
	 * @return a new Builder instance
	 */
	public static Builder<?> builder() {
		return new Builder<>();
	}

	/**
	 * Builder for creating instances of ToolSearchToolCallingAdvisor.
	 * <p>

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Use a standard, unmodified JDK/JRE (Temurin, Oracle, Corretto) that includes the SUN security provider with SHA-256.
2. Check java.security config (JAVA_HOME/conf/security/java.security) and restore the SUN provider entry if it was removed.
3. If using jlink, include the org.builtin.providers / jdk.crypto modules in the custom runtime image.
4. If you cannot fix the runtime, upgrade spring-ai or wrap advisor creation to fail fast with a clearer message.

Example fix

// before (broken custom runtime)
java -module-path custom-modules ... // no jdk.crypto.evr/sun provider

// after
jlink --add-modules java.base,jdk.crypto.ec,java.security.jgss --output myruntime

try { MessageDigest.getInstance("SHA-256"); } catch (NoSuchAlgorithmException e) { throw new IllegalStateException("Runtime lacks SHA-256; check JCA providers", e); }

boolean sha256Available() { try { MessageDigest.getInstance("SHA-256"); return true; } catch (NoSuchAlgorithmException e) { return false; } }

try {
    advisor = ToolSearchToolCallingAdvisor.builder().build();
} catch (IllegalStateException e) {
    if (e.getCause() instanceof NoSuchAlgorithmException) {
        throw new RuntimeException("JVM JCA providers missing SHA-256; use a standard JDK", e);
    }
    throw e;
}

When it happens

Trigger: Calling fingerprint()/build() of ToolSearchToolCallingAdvisor when MessageDigest.getInstance("SHA-256") throws NoSuchAlgorithmException — i.e. no JCA provider offers SHA-256.

Common situations: Running on a stripped-down JVM or custom runtime (e.g. a heavily trimmed jlink image without the SUN provider), a broken java.security configuration file that removed the SUN provider, or exotic JDK distributions without standard providers.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• NoSuchAlgorithmException (wrapped IllegalArgumentException)
• Failed to read stdio connection resource
• SSE connection '<connectionName>' requires a 'url' property.
• Failed to create SSE transport for connection '<connectionNa
• The region '<region>' is not a valid region!

AI-assisted analysis of spring-projects/spring-ai@98a7beda4f (2026-09-11). Data as JSON: /api/errors/d2c07809a725ba7a. Report an issue: GitHub.