quarkusio/quarkus · error · RuntimeException

Failed to notify the Quarkus management endpoint

Error message

Failed to notify the Quarkus management endpoint

What it means

certificateChainAndKeyAreReady POSTs to <management-url>/q/lets-encrypt/certs to tell the running Quarkus app that a new certificate chain and private key are available so it can reload the TLS registry. If the endpoint responds with anything other than 204 No Content, the client throws this RuntimeException. It means the app did not accept the certificate-ready notification.

Source

Thrown at extensions/tls-registry/cli/src/main/java/io/quarkus/tls/cli/letsencrypt/AcmeClient.java:232

        addKeyAndUser(request);
        HttpResponse<Buffer> response = await(request.send());
        if (response.statusCode() != 204) {
            throw new RuntimeException("Failed to clear challenge content in the Quarkus management endpoint");
        }
    }

    public void certificateChainAndKeyAreReady() {
        LOGGER.info(
                "\uD83D\uDD35 Notifying management challenge endpoint that a new certificate chain and private key are ready");

        // Check rate limit before notification
        checkRateLimit("certificate-notification");

        HttpRequest<Buffer> request = managementClient.postAbs(certsUrl);
        addKeyAndUser(request);
        HttpResponse<Buffer> response = await(request.send());
        if (response.statusCode() != 204) {
            throw new RuntimeException("Failed to notify the Quarkus management endpoint");
        }
    }

    private void addKeyAndUser(HttpRequest<Buffer> request) {
        if (managementKey != null) {
            AUDIT.info("Using API key authentication for management endpoint");
            request.addQueryParam("key", managementKey);
        } else if (managementUser != null && managementPassword != null) {
            AUDIT.info("Using basic authentication for management endpoint (user: " + managementUser + ")");
            request.basicAuthentication(managementUser, managementPassword);
        } else {
            AUDIT.warn("No authentication credentials provided for management endpoint");
        }
    }

    private <T> T await(Future<T> future) {
        try {
            return future.toCompletionStage().toCompletableFuture().get(30, TimeUnit.SECONDS);

View on GitHub (pinned to e1c734241f)

Solutions

1. Check the app logs for the reload failure; if 500, validate the written PEM files (openssl x509/openssl pkey) and file permissions (owner-only rw for the key).
2. If 404, rebuild/redeploy the app with quarkus.tls.lets-encrypt.enabled=true.
3. Fix credentials: pass the correct --key or --user/--password matching the management endpoint configuration.
4. Verify the management URL and port passed to the CLI match quarkus.management.host/port.
5. Ensure the app is healthy and retry the notification after fixing the underlying cause.

Example fix

// before: POST /q/lets-encrypt/certs -> 500 because key file unreadable
// key file mode 644, running as non-owner

// after: correct ownership/permissions then retry
// chown appuser:appuser cert.pem key.pem
// chmod 600 key.pem
// then re-run the notify step (or the whole 'lets-encrypt renew' command)

// pre-flight: app running and endpoint enabled/auth ok
// curl -i -u user:pass -X POST https://host:9000/q/lets-encrypt/certs  (expect 2xx family, app must have valid PEMs ready)
// validate written files first:
// openssl x509 -in cert.pem -noout && openssl pkey -in key.pem -noout

boolean notified = false;
for (int attempt = 0; attempt < 3 && !notified; attempt++) {
    try {
        acmeClient.certificateChainAndKeyAreReady();
        notified = true;
    } catch (RuntimeException e) {
        if (e.getMessage() != null && e.getMessage().contains("Failed to notify the Quarkus management endpoint")) {
            Thread.sleep(5000L * (attempt + 1)); // app may be reloading/starting
        } else {
            throw e;
        }
    }
}
if (!notified) throw new RuntimeException("App never accepted certificate notification");

When it happens

Trigger: POST certsUrl returns a non-204 status: 404 when quarkus.tls.lets-encrypt.enabled is false or the app exposes no lets-encrypt management endpoint; 401/403 for wrong/missing --key or --user/--password; 5xx when the app fails to load the new certificate files (unreadable/invalid PEM); connection to the wrong management URL/port.

Common situations: Renewing a certificate while the app runs with a build that never enabled the lets-encrypt management endpoints; rotated management API key not yet updated in CLI config; certificate files written to a path the app cannot read, causing a 500 during reload; app crashed mid-renewal.

Related errors

• Failed to clear challenge content in the Quarkus management
• The private key cannot be null
• The certificate chain cannot be null or empty
• Rate limit exceeded: too many ACME challenge requests. Wait
• Missing certificate authority challenge

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