quarkusio/quarkus · error · IllegalArgumentException

You must specify the key files and certificate files

Error message

You must specify the key files and certificate files

What it means

PemKeyCertConfig.toOptions() builds Vert.x PemKeyCertOptions from the configured keyCerts map; if keyCerts is empty there is no key/cert material at all, so it throws an IllegalArgumentException requiring key files and certificate files to be specified. A keystore cannot be constructed without any key pair.

Source

Thrown at extensions/tls-registry/runtime/src/main/java/io/quarkus/tls/runtime/config/PemKeyCertConfig.java:40

    /**
     * List of the PEM key/cert files (Pem format).
     */
    @WithParentName
    Map<String, KeyCertConfig> keyCerts();

    /**
     * The order of the key/cert files, based on the names in the `keyCerts` map.
     * <p>
     * By default, Quarkus sorts the key using a lexicographical order.
     * This property allows you to specify the order of the key/cert files.
     */
    Optional<List<String>> order();

    default PemKeyCertOptions toOptions() {
        PemKeyCertOptions options = new PemKeyCertOptions();

        if (keyCerts().isEmpty()) {
            throw new IllegalArgumentException("You must specify the key files and certificate files");
        }

        List<KeyCertConfig> orderedListOfPair = new ArrayList<>();
        if (order().isPresent()) {
            // Check the size of the order list. It must match the size of the keyCerts map.
            if (order().get().size() != keyCerts().size()) {
                throw new IllegalArgumentException("The size of the `order` list (" + order().get().size() + ") must " +
                        "match the size of the `keyCerts` map (" + keyCerts().size() + ")");
            }

            // We use the order specified by the user.
            for (String name : order().get()) {
                KeyCertConfig keyCert = keyCerts().get(name);
                if (keyCert == null) {
                    throw new IllegalArgumentException("The key/cert pair with the name '" + name
                            + "' is not found in the `order` list: " + order().get());
                }
                orderedListOfPair.add(keyCert);

View on GitHub (pinned to e1c734241f)

Solutions

1. Add at least one entry: quarkus.tls.<name>.key-store.pem.keyCerts.<alias>.cert=<cert path> and .key=<key path>
2. If you intended a keystore provider instead, remove the pem block and register the KeyStoreProvider bean
3. Verify the property keys are correct (keyCerts.<alias>.key / .cert) and not filtered out by a profile or build-time condition

Example fix

// before
quarkus.tls.my.key-store.pem.sni=true   # no keyCerts entries
// after
quarkus.tls.my.key-store.pem.keyCerts.default.key=/etc/certs/server-key.pem
quarkus.tls.my.key-store.pem.keyCerts.default.cert=/etc/certs/server-cert.pem
quarkus.tls.my.key-store.pem.sni=true

var pem = tlsConfig.keyStore().pem();
if (pem.isPresent() && pem.get().keyCerts().isEmpty())
    throw new IllegalStateException("key-store.pem enabled but no keyCerts entries configured");

try {
    options = pemKeyCertConfig.toOptions();
} catch (IllegalArgumentException e) {
    throw new IllegalStateException("Add keyCerts.<alias>.key/.cert properties", e);
}

When it happens

Trigger: quarkus.tls.<name>.key-store.pem.keyCerts is empty/absent while the pem group itself is present (e.g. only pem.sni or other keys set), so toOptions() has nothing to load — e.g. via quarkus.tls.<name>.key-store.pem enabled with no keyCerts entries.

Common situations: Defining quarkus.tls.<name>.key-store.pem without any .keyCerts.<alias>.key/.cert entries; generating config properties programmatically where the map was never populated; renaming the alias namespace so the old entries no longer match; enabling TLS but expecting credentials from elsewhere (provider is a separate mechanism).

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• You must specify the key files and certificate files
• Invalid keystore '" + name + "' - Only one keystore type can
• Configured certificate path does not exist: + certificateDir
• Path '" + certificateDirectory + "' is not a directory. Path
• The size of the `order` list (N) must match the size of the

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/6fb7b3d233129481. Report an issue: GitHub.