{"record":{"id":"d00a5371685aeccc","repo":"quarkusio/quarkus","slug":"failed-to-clear-challenge-content-in-the-quarkus-m","errorCode":null,"errorMessage":"Failed to clear challenge content in the Quarkus management endpoint","messagePattern":"Failed to clear challenge content in the Quarkus management endpoint","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"extensions/tls-registry/cli/src/main/java/io/quarkus/tls/cli/letsencrypt/AcmeClient.java","lineNumber":217,"sourceCode":"\n        Assert.checkNotNullParam(\"account\", account);\n        Assert.checkNotNullParam(\"challenge\", challenge);\n        // ensure the token is valid before proceeding\n        String token = challenge.getToken();\n        if (!token.matches(TOKEN_REGEX)) {\n            throw new RuntimeException(\"Invalid certificate authority challenge\");\n        }\n\n        LOGGER.debugf(\"Requesting the management challenge endpoint to delete a challenge resource %s\", token);\n\n        // Check rate limit before cleanup\n        checkRateLimit(\"challenge-cleanup\");\n\n        HttpRequest<Buffer> request = managementClient.deleteAbs(challengeUrl);\n        addKeyAndUser(request);\n        HttpResponse<Buffer> response = await(request.send());\n        if (response.statusCode() != 204) {\n            throw new RuntimeException(\"Failed to clear challenge content in the Quarkus management endpoint\");\n        }\n    }\n\n    public void certificateChainAndKeyAreReady() {\n        LOGGER.info(\n                \"\\uD83D\\uDD35 Notifying management challenge endpoint that a new certificate chain and private key are ready\");\n\n        // Check rate limit before notification\n        checkRateLimit(\"certificate-notification\");\n\n        HttpRequest<Buffer> request = managementClient.postAbs(certsUrl);\n        addKeyAndUser(request);\n        HttpResponse<Buffer> response = await(request.send());\n        if (response.statusCode() != 204) {\n            throw new RuntimeException(\"Failed to notify the Quarkus management endpoint\");\n        }\n    }\n","sourceCodeStart":199,"sourceCodeEnd":235,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/tls-registry/cli/src/main/java/io/quarkus/tls/cli/letsencrypt/AcmeClient.java#L199-L235","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Verify the Quarkus application is running and reachable at the management URL passed to the tool (curl -X DELETE it manually).","Fix authentication: supply the correct --key (API key) or --user/--password matching quarkus.management.basic-auth or the configured API key.","Confirm the management host/port (quarkus.management.host/port) matches the URL used by the CLI tool.","Treat this as transient during restarts: wait for the app to be up (checkReadiness()) and re-run the cleanup/renewal."],"exampleFix":"// before: app built without the endpoint -> DELETE returns 404\n// quarkus.tls.lets-encrypt.enabled=false (default)\n\n// after: application.properties (rebuild required)\n// quarkus.tls.lets-encrypt.enabled=true\n// quarkus.management.enabled=true\n// then verify:\n// curl -u admin:secret -X DELETE https://host:9000/q/lets-encrypt/challenge","handlingStrategy":"validation","validationCode":"// before running the tool, verify the endpoint exists and auth works:\n// curl -i -u user:pass https://host:9000/q/lets-encrypt/challenge  -> expect 200/204, not 404/401\n// app must be built with quarkus.tls.lets-encrypt.enabled=true","typeGuard":"static boolean challengeEndpointReady(AcmeClient client) {\n    return client.checkReadiness();\n}","tryCatchPattern":"try {\n    acmeClient.cleanupAfterChallenge(account, challenge);\n} catch (RuntimeException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"Failed to clear challenge content\")) {\n        // stale challenge content is usually harmless: log a warning and continue,\n        // or wait for the app and retry once\n    } else {\n        throw e;\n    }\n}","preventionTips":["Ensure quarkus.tls.lets-encrypt.enabled=true at build time before running renewal tooling.","Call AcmeClient.checkReadiness() before challenge operations and wait/retry until it returns true.","Keep CLI --key / --user/--password in sync with the app's management auth configuration.","Avoid restarting the app between challenge upload and cleanup; if it happens, re-check readiness first."],"tags":["acme","lets-encrypt","management-endpoint","http-delete"],"backgroundTag":"management-endpoint-request-failed","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}