quarkusio/quarkus · error · RuntimeException

Failed to clear challenge content in the Quarkus management

Error message

Failed to clear challenge content in the Quarkus management endpoint

What it means

After HTTP-01 validation, cleanupAfterChallenge sends an HTTP DELETE to the Quarkus management endpoint <management-url>/q/lets-encrypt/challenge to remove the previously uploaded challenge content. The endpoint is expected to answer 204 No Content; any other status code (404, 401, 500...) makes the client throw this RuntimeException. It signals the running Quarkus application did not (or could not) clear the challenge resource.

Source

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

        Assert.checkNotNullParam("account", account);
        Assert.checkNotNullParam("challenge", challenge);
        // ensure the token is valid before proceeding
        String token = challenge.getToken();
        if (!token.matches(TOKEN_REGEX)) {
            throw new RuntimeException("Invalid certificate authority challenge");
        }

        LOGGER.debugf("Requesting the management challenge endpoint to delete a challenge resource %s", token);

        // Check rate limit before cleanup
        checkRateLimit("challenge-cleanup");

        HttpRequest<Buffer> request = managementClient.deleteAbs(challengeUrl);
        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");
        }
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Check the actual status in the app/server logs; a 404 means enable the endpoint at build time with quarkus.tls.lets-encrypt.enabled=true and rebuild.
2. Verify the Quarkus application is running and reachable at the management URL passed to the tool (curl -X DELETE it manually).
3. Fix authentication: supply the correct --key (API key) or --user/--password matching quarkus.management.basic-auth or the configured API key.
4. Confirm the management host/port (quarkus.management.host/port) matches the URL used by the CLI tool.
5. Treat this as transient during restarts: wait for the app to be up (checkReadiness()) and re-run the cleanup/renewal.

Example fix

// before: app built without the endpoint -> DELETE returns 404
// quarkus.tls.lets-encrypt.enabled=false (default)

// after: application.properties (rebuild required)
// quarkus.tls.lets-encrypt.enabled=true
// quarkus.management.enabled=true
// then verify:
// curl -u admin:secret -X DELETE https://host:9000/q/lets-encrypt/challenge

// before running the tool, verify the endpoint exists and auth works:
// curl -i -u user:pass https://host:9000/q/lets-encrypt/challenge  -> expect 200/204, not 404/401
// app must be built with quarkus.tls.lets-encrypt.enabled=true

static boolean challengeEndpointReady(AcmeClient client) {
    return client.checkReadiness();
}

try {
    acmeClient.cleanupAfterChallenge(account, challenge);
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().contains("Failed to clear challenge content")) {
        // stale challenge content is usually harmless: log a warning and continue,
        // or wait for the app and retry once
    } else {
        throw e;
    }
}

When it happens

Trigger: DELETE challengeUrl returns a status other than 204 — most commonly 404 because quarkus.tls.lets-encrypt.enabled is not true or the application is not running/exposed; 401/403 when management auth credentials are wrong or missing; 5xx from an application error; also when the URL passed to the AcmeClient constructor doesn't point at the app's management interface.

Common situations: App redeployed or restarted between challenge upload and cleanup; quarkus.management enabled but lets-encrypt endpoint disabled at build time; wrong --key/--user/--password CLI credentials; management interface bound to a different port/host than the URL given to the tool; corporate proxy intercepting the DELETE.

Related errors

• Failed to notify the Quarkus management endpoint
• 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/d00a5371685aeccc. Report an issue: GitHub.