spring-projects/spring-boot · error · IllegalStateException

Error loading private key file: {}

Error message

Error loading private key file: {}

What it means

PemPrivateKeyParser.parse(text, password) loops over PEM_PARSERS (PKCS1 RSA, SEC1 EC, PKCS8, encrypted PKCS8). The catch (Exception ex) at line 217 wraps any exception from any parser strategy — DER decode failure, key-spec construction, KeyFactory failure, or the encrypted-key decryptor throwing IllegalArgumentException — into IllegalStateException with the underlying message.

Source

Thrown at buildpack/spring-boot-buildpack-platform/src/main/java/org/springframework/boot/buildpack/platform/docker/ssl/PemPrivateKeyParser.java:218

	 * decryption if necessary.
	 * @param text the text to parse
	 * @param password the password used to decrypt an encrypted private key
	 * @return the parsed private key
	 */
	static @Nullable PrivateKey parse(@Nullable String text, @Nullable String password) {
		if (text == null) {
			return null;
		}
		try {
			for (PemParser pemParser : PEM_PARSERS) {
				PrivateKey privateKey = pemParser.parse(text, password);
				if (privateKey != null) {
					return privateKey;
				}
			}
		}
		catch (Exception ex) {
			throw new IllegalStateException("Error loading private key file: " + ex.getMessage(), ex);
		}
		throw new IllegalStateException("Missing private key or unrecognized format");
	}

	/**
	 * Parser for a specific PEM format.
	 */
	private static class PemParser {

		private final Pattern pattern;

		private final BiFunction<byte[], @Nullable String, PKCS8EncodedKeySpec> keySpecFactory;

		private final String[] algorithms;

		PemParser(String header, String footer,
				BiFunction<byte[], @Nullable String, PKCS8EncodedKeySpec> keySpecFactory, String... algorithms) {
			this.pattern = Pattern.compile(header + BASE64_TEXT + footer, Pattern.CASE_INSENSITIVE);

View on GitHub (pinned to 270dfe353f)

Solutions

1. If the key is encrypted, supply the correct password via the parse(text, password) overload.
2. Re-export the key in unencrypted PKCS8 PEM: `openssl pkcs8 -topk8 -nocrypt -in key.pem -out key-pkcs8.pem`.
3. Inspect the wrapped cause for the specific parser error (the message is ex.getMessage()).

// Validate the key with openssl before invoking the build
Process p = new ProcessBuilder("openssl", "pkey", "-in", keyPath.toString(), "-noout", "-passin", "pass:" + pw)
        .redirectErrorStream(true).start();
if (p.waitFor() != 0) {
    throw new IllegalArgumentException("Invalid or undecryptable private key at " + keyPath);
}

try {
    PemPrivateKeyParser.parse(text, password);
} catch (IllegalStateException ex) {
    Throwable c = ex.getCause();
    if (c instanceof IllegalArgumentException iae
            && iae.getMessage().contains("decrypting")) {
        // prompt for the correct password and retry
    } else {
        // hint: convert key to standard PKCS8 PEM
    }
    throw ex;
}

When it happens

Trigger: A PEM block matched one of the header regexes, but parsing failed midway: e.g. Pkcs8PrivateKeyDecryptor.decrypt threw IllegalArgumentException because of a wrong password; DerElement parsing hit a malformed ASN.1 structure; KeyFactory.generatePrivate threw InvalidKeySpecException that escaped (note: InvalidKeySpecException inside PemParser.parse is normally swallowed, so an escape here means a different path); createKeySpecForAlgorithm's DerEncoder IO failure.

Common situations: Encrypted private key with the wrong password (bubbles up from Pkcs8PrivateKeyDecryptor); DER bytes truncated or corrupted; key algorithm OID not in the ALGORITHMS map combined with a KeyFactory failure.

Related errors

• Missing private key or unrecognized format
• Error reading certificate: {}
• Error decrypting private key
• Error adding certificates to KeyStore: {}
• Error creating KeyStore: {}

AI-assisted analysis of spring-projects/spring-boot@270dfe353f (2026-08-11). Data as JSON: /api/errors/f2fc9166836f5350. Report an issue: GitHub.