Troubleshooting · 15.3
HTTP-01 and TLS-ALPN-01
With HTTP-01, the CA fetches http://<public-name>/.well-known/acme-challenge/…. TLSPilot publishes the file with the option selected for the certificate: Listener on this management host (port 80), Local webroot on this management host, Remote Windows web server (WinRM) or Remote Linux web server (SSH). With TLS-ALPN-01, the CA opens a TLS connection with the protocol acme-tls/1, and TLSPilot answers it on the management host with a temporary challenge certificate. The CA always connects to port 80 (HTTP-01) or 443 (TLS-ALPN-01) of the public name; other ports are not possible (RFC 8555, RFC 8737). It connects from several network perspectives, see chapter Multi-perspective validation.
| Symptom | Cause | Solution |
|---|---|---|
| HTTP-01 | ||
| Failed to start HTTP-01 listener on port 80 of this management host. | Port 80 is already used on the management host, for example by IIS or another web server. The listener always uses port 80; another local port is not possible. | Free port 80, or publish the file with Local webroot, Remote Windows or Remote Linux where the public name points. |
| That is an HTTP-01 failure (the CA looks up A/AAAA and port 80). | The CA could not fetch the file: the name does not point to the server with the file, or port 80 is blocked. | Check the A/AAAA records of the name and open port 80 from the internet, see chapter Ports and listeners. For DNS-01, select DNS-01 as challenge type and save. |
| HTTP-01 fails although the file is on the web server | A reverse proxy, load balancer or NAT rule sends the request to another server, or a redirect leads to a port other than 80 or 443. Let’s Encrypt follows up to 10 redirects, only to http or https on port 80 or 443. | Forward /.well-known/acme-challenge/ on port 80 to the server where TLSPilot publishes the file. With several web servers behind a load balancer, every server must deliver the file, or use DNS-01. |
| HTTP-01 Local webroot requires a path, HTTP-01 Remote Windows requires Target host. or … requires web root path | A required field of the selected option is empty. | Enter the target host and the web root, for example C:\inetpub\wwwroot or /var/www/html. |
| WinRM credential <name> not found or incomplete. or SSH credential <name> not found or incomplete. | Remote Windows needs a WinRM credential, Remote Linux an SSH credential. | Select or create the matching credential in the Credentials Manager. |
| TLS-ALPN-01 | ||
| Authorization invalid for <name> with TLS-ALPN-01: the CA must complete a TLS handshake with acme-tls/1 on TCP/443. A timeout means inbound 443 is filtered. …, and the details of the CA report a timeout | Port 443 is blocked by a firewall, there is no NAT rule to the management host, or the names do not point to the management host. | Open port 443 from the internet and forward it to the management host. TLS-ALPN-01 only works if all names point to the management host; otherwise use DNS-01 or HTTP-01. |
| Same message, but the details of the CA report that the handshake ended or that no or a wrong certificate was presented (Handshake EOF / no certificate means the challenge cert was not presented.) | Another system answers on port 443, for example a reverse proxy, load balancer or WAF that terminates TLS. It presents its own certificate, and acme-tls/1 does not get through to TLSPilot. | Forward port 443 at TCP level to the management host, without TLS termination, or use DNS-01 or HTTP-01. |
| Log: TLS-ALPN-01 could not bind <address>:<port> (already in use) | Another process uses the port. TLSPilot then places the challenge certificate in a shared store. This only works if the HTTPS listener of the WebUI is the process on that port. | If IIS or another service uses port 443, enter a free IP address under Listen address in the TLS-ALPN-01 settings of the certificate, or another Port with forwarding, see chapter Additional challenge types. |
| TLS-ALPN-01 cannot listen on <address>:<port>: … If the Web UI already uses 443, pick another local IP for this challenge or stop the conflicting listener. | TLSPilot cannot open the listener, for example because the listen address does not exist on the management host. | Enter an IP address of the management host, or 0.0.0.0 for all IPv4 addresses, under Listen address. |
| The Port of TLS-ALPN-01 is not 443, and the validation times out | The CA always connects to port 443. It only reaches the local port if a firewall, NAT or WAF forwards external port 443 to it. | Forward external port 443 at TCP level to the listen address and port, see chapter Additional challenge types. |
| TLS-ALPN-01 on <certificate> does not support IP SANs. Use DNS-01 or Private CA. | TLS-ALPN-01 cannot validate IP addresses. | Use DNS-01 or the Private CA. |
| HTTP-01 and TLS-ALPN-01 | ||
| The validation fails although it works over IPv4, for example with a test from outside | The name has an AAAA record that points to another server or is not reachable. Let’s Encrypt prefers IPv6 and only retries over IPv4 after a timeout; for HTTP-01 only on the first request, not after a redirect. With the default listen address 0.0.0.0, the TLS-ALPN-01 listener only accepts IPv4. | Correct the AAAA record so that it points to the right server, or remove it if the name is not meant to work over IPv6. |
| The validation fails at some attempts only, or the details of the CA contain secondary validation | Geo-blocking, an IP allowlist or a WAF rule blocks some network perspectives of the CA. Let’s Encrypt does not publish the IP addresses it validates from, and they can change at any time. | Allow port 80 or 443 from all of the internet, at least for the time of the validation and for /.well-known/acme-challenge/. See chapter Multi-perspective validation. |