jenkinsci/jenkins · critical · IllegalStateException

SHA-256 could not be instantiated, but is required to be imp

Error message

SHA-256 could not be instantiated, but is required to be implemented by the language specification

What it means

Wraps NoSuchAlgorithmException when MessageDigest.getInstance("SHA-256") fails. Per the Java specification (JCA reference guide), SHA-256 is a mandatory algorithm that every compliant JVM must provide, so this exception indicates a fundamentally broken JVM environment rather than a normal runtime condition.

Source

Thrown at core/src/main/java/hudson/Util.java:2031

     */
    @Restricted(value = NoExternalUse.class)
    static boolean GC_AFTER_FAILED_DELETE = SystemProperties.getBoolean(Util.class.getName() + ".performGCOnFailedDelete");

    private static PathRemover newPathRemover(@NonNull PathRemover.PathChecker pathChecker) {
        return PathRemover.newFilteredRobustRemover(pathChecker, DELETION_RETRIES, GC_AFTER_FAILED_DELETE, WAIT_BETWEEN_DELETION_RETRIES);
    }

    /**
     * Returns SHA-256 Digest of input bytes
     */
    @Restricted(NoExternalUse.class)
    public static byte[] getSHA256DigestOf(@NonNull byte[] input) {
        try {
                MessageDigest messageDigest = MessageDigest.getInstance("SHA-256");
                messageDigest.update(input);
                return messageDigest.digest();
        } catch (NoSuchAlgorithmException noSuchAlgorithmException) {
            throw new IllegalStateException("SHA-256 could not be instantiated, but is required to" +
                    " be implemented by the language specification", noSuchAlgorithmException);
        }
    }

    /**
     * Returns Hex string of SHA-256 Digest of passed input
     */
    @Restricted(NoExternalUse.class)
    public static String getHexOfSHA256DigestOf(byte[] input) {
        //get hex string of sha 256 of payload
        byte[] payloadDigest = Util.getSHA256DigestOf(input);
        return (payloadDigest != null) ? Util.toHexString(payloadDigest) : null;
    }


    /**
     * Returns Hex string of SHA-256 Digest of passed string
     */

View on GitHub (pinned to 2e228ff40b)

Solutions

Verify the JVM is a standard OpenJDK or Oracle JDK distribution — a full JDK always includes SHA-256.
Check java.security file (in $JAVA_HOME/conf/security/java.security) to ensure the default Sun (or SunRsaSign/SunEC) provider is listed.
If using a FIPS provider (e.g., BouncyCastle FIPS), ensure it is correctly registered in java.security and its JAR is on the classpath.

Defensive patterns

Strategy: try-catch

Validate before calling

// Verify SHA-256 availability at startup
try {
    MessageDigest.getInstance("SHA-256");
} catch (NoSuchAlgorithmException e) {
    throw new IllegalStateException("JVM does not provide SHA-256 — check java.security providers", e);
}

Try / catch

try {
    byte[] digest = Util.getSHA256DigestOf(input);
} catch (IllegalStateException e) {
    // This should never happen on a compliant JVM
    // Fall back to an alternative provider or fail hard
    throw new ServletException("Critical JVM misconfiguration: SHA-256 unavailable", e);
}

Prevention

Use a standard JDK distribution (OpenJDK, Oracle JDK) rather than stripped JVMs.
Do not modify java.security to remove default JCA providers.
If using FIPS mode, validate the security provider registration during deployment testing.

When it happens

Trigger: MessageDigest.getInstance("SHA-256") throws NoSuchAlgorithmException — the JVM's security provider list does not include an implementation of SHA-256. This is only possible with a custom or severely stripped JVM, a misconfigured security provider list (e.g., java.security file with all providers removed), or a FIPS-mode configuration that fails to register a SHA-256 provider.

Common situations: Custom JRE build with stripped JCA providers; java.security file modified to remove the default Sun provider; FIPS-compliant JVM configured incorrectly where the BouncyCastle FIPS provider is not properly registered; running on an embedded JVM that doesn't implement the full JCA specification.

Related errors

AI-assisted analysis of jenkinsci/jenkins@2e228ff40b (2026-08-14). Data as JSON: /api/errors/ae25bdf245597aaa. Report an issue: GitHub.