FAQ and Troubleshooting

I have lost my account key pair. What can I do?

There is no automatic way to recover the key pair or restore access to your account.

If you just create a new account with a new key pair, subsequent domain authorization attempts are likely to fail because there is already such an authorization associated with your old account.

All you can do is to contact the CA support hotline and ask for support.

You can still revoke certificates without account key pair though, see here.

I suddenly get "Network error" when connecting to Pebble.

Symptom: When connecting to Pebble, org.shredzone.acme4j.exception.AcmeNetworkException: Network error exceptions are thrown, with PKIX path building failed mentioned as cause. The code has worked before.

Cause: Starting with v2.9.0, Pebble uses a new self-signed certificate for its API connection. It doesn't match the certificate stored in acme4j before v4.0.0.

Solution: Update to acme4j v4.0.0 or higher.

If you cannot update acme4j, download Pebble's certificate from here. Store the file either as resource (e.g. src/main/resources or src/test/resources, respectively), or as META-INF. It will override the stored certificate. (This workaround only affects the Pebble provider, and is safe for production use.)

My Challenge is in status PENDING. What does it mean?

Symptom: After the challenge was triggered, it changes to status PENDING.

Cause: You have triggered the challenge, and are now waiting for the CA to verify it.

Solution: Wait until the challenge changes to either VALID or INVALID state. Do not remove challenge related resources (e.g. HTML files or DNS records) before.

My Challenge returns status INVALID. What has gone wrong?

Symptom: After the challenge was triggered, it eventually changes to status INVALID.

Cause: There may be multiple causes for that, but usually it means that the CA could not verify your challenge.

Solution: If the status is INVALID, invoke Challenge.getError() to get the cause of the failure. For example, you can log the output of challenge.getError().toString(). Make sure that your challenge is ready for verification before you invoke Challenge.trigger(). Also make sure not to remove the challenge until the status is either VALID or INVALID. Read more about errors here.

My Order returns status INVALID. What has gone wrong?

Symptom: Your challenge(s) passed as VALID. However, when you execute the order, it changes to status INVALID. No certificate was issued.

Cause: There may be multiple reasons for that. It seems that you are still missing steps that are required by the CA before completion.

Solution: If the status is INVALID, invoke Order.getError() to get the cause of the failure. For example, you can log the output of order.getError().toString(). Also see here.

My Order seems to be stuck in status PROCESSING. What can I do?

Symptom: Your challenge(s) passed as VALID. However, when you execute the order, it seems to be stuck in status PROCESSING.

Cause: The CA may have retained your order to carry out background checks. These checks can take hours or even days. Please read the CA documentation for further details.

Solution: There is nothing you can do on software side.

Browsers do not accept my certificate.

Symptom: A certificate was successfully issued. However, the browser does not accept the certificate, and shows an error that the cert authority is invalid.

Cause: This problem occurs when the staging server of a CA is used (e.g. acme://letsencrypt.org/staging). The certificate is signed correctly, but the staging issuer certificate is not known to the browser.

Solution: Use the production server of your CA (e.g. acme://letsencrypt.org).

The http-01 challenge fails.

Symptom: You set up your response token in the /.well-known/acme-challenge/ path, and you can also successfully fetch it locally, but the challenge is failing with Invalid response: 404 (or another HTTP error code).

Cause: The CA could not access your response token, but gets a 404 page (or some other kind of error page) instead. Bear in mind that the response token is not evaluated locally by acme4j, but is fetched by the CA server.

Solution: The CA server could not access your response token from the outside. One reason may be that a firewall or reverse proxy is blocking the access. Another reason may be that your local DNS resolves the domain differently. The CA uses public DNS servers to resolve the domain name. This error often happens when you try to validate a foreign domain (e.g. example.com or example.org).

Account.getOrders() fails with an exception.

Symptom: According to RFC 8555, it should be possible to get a list of all orders of an account. But when I invoke Account.getOrders(), an AcmeProtocolException is thrown.

Cause: Let's Encrypt does not support getting a list of orders, even though it is mandatory by RFC 8555 (see this issue).

Solution: There is no solution. You need to store the location of your orders locally, and use Login.bindOrder() to rebind the location to your session and restore the Order object.

The S/MIME certificate challenge fails.

Symptom: You try to order an S/MIME certificate from a providing CA. However, the CA constantly refuses the response e-mail because the contained ACME response is purportedly invalid.

Cause: Unfortunately RFC 8823 has an ambiguous specification about how to concatenate the two token parts. The text permits two different interpretations that may give different results. acme4j uses an implementation that corresponds to the intention of the author of RFC 8823. If the CA is implemented following the other interpretation, the ACME e-mail response will not match (see this issue).

Solution: It is a difficult situation that is caused by an ambiguous specification, but it is like it is now. Since acme4j follows the intention of the RFC author, I take the position that the acme4j implementation is correct. Please open a bug report at the CA, and refer to this issue. If the two tokens are split at a position, so the first token won't have trailing base64 padding bits, the CA service can be implemented in a way that is compatible to both interpretations.

Suddenly acme4j starts throwing AcmeUserActionRequiredException everywhere! How can I fix that?

Symptom: Many acme4j methods suddenly throw a AcmeUserActionRequiredException after interacting with the server. It is impossible to order certificates.

Cause: The CA has probably changed its terms of service and wants you to accept them before resuming.

Solution: Invoke AcmeUserActionRequiredException.getInstance() to get a URL of a web page that describes all further steps to be taken. You might also be able to resolve the issue by logging into your CA's account, but that is up to the CA's discretion.

Unfortunately, manual action is required in any case, there is no way to automate this process. This is an intentional protocol decision, and acme4j is just the messenger.

Can you support us in complying with the EU Cyber Resilience Act (CRA)?

No. I'm not legally required to do so.

acme4j is developed and maintained by one person in their free time, with no company or organization behind it. It is non-commercial, not monetized, and there is no intent to make profit.

In other words: This software is a gift. If you use it in a commercial context, you may have obligations under the CRA, but I don't.

Please understand that while I welcome open collaboration and feedback, I cannot provide legal compliance support for third-party commercial use.

Development seems to be very slow. Why is that?

There are two main reasons:

  1. The code base is mature and stable. First released in December 2015, it has grown into a well-tested and reliable piece of software. With high unit test coverage and regular integration tests against a Pebble server, known issues have been fixed quickly over the years. That's why updates are rare: there's simply not much to do. Which means you get to enjoy a stable, dependable library.

  2. It's a volunteer effort. This project is maintained by a single person in their free time, with no company or funding behind it. Development happens when there's time and motivation. But after a decade of work, other priorities sometimes come first. While that means fewer updates, it also means the project isn't driven by deadlines or commercial pressure.

Where can I find the acme4j Repository?

  • The main repository is hosted at Codeberg.
  • There is a fully functional mirror at GitHub.

You can use both sites for posting issues and pull requests. However, Codeberg is the preferred repository.

Where can I find more help?