A quick work around certificate checking issues on Onionspray backends
relying on Let’s Encrypt certificates.
This is not about HTTPS certificates for onionsites using
Onionspray, but checking the certificates of the backend
onionsites being onionized.
The problem
Let’s Encrypt recently introduced a New “Generation Y” Hierarchy of Root and
Intermediate Certificates - Let’s Encrypt, which were deployed on last
May 13.
As this change still did not reach the ca-certificates package on
Debian-like systems (Debian bug #1139720), reverse HTTPS proxies getting
content from backends using certificates issued by Let’s Encrypt might
get a 502 Bad Gateway error response if they check certificates against
/etc/ssl/certs/ca-certificates.crt.
In the case of Onionspray, the message is a NGINX gateway error:
502 Bad Gateway
openresty
The specific issue will show up in the proxy error log:
onion@onion:~/onionspray$ tail -f projects/example.org/log/nginx-error.log
2026/08/06 19:57:38 [error] 1448#0: *1801 upstream SSL certificate verify
error: (20:unable to get local issuer certificate) while SSL handshaking to
upstream, client: unix:, server:
exaymhwjhgdopeebkv5p3lmb5vu2mmvcc7krpgwx6ngf4uvob2whkcqd.onion, request:
"GET / HTTP/1.1", upstream: "https://192.0.2.120:443/", host:
"www.exaymhwjhgdopeebkv5p3lmb5vu2mmvcc7krpgwx6ngf4uvob2whkcqd.onion"
Workaround
The workaround consists in appending the new Let’s Encrypt Root certificate in a copy of
Debian’s ca-certificates.crt:
onion@onion:~/onionspray$ cp /etc/ssl/certs/ca-certificates.crt projects/example/ssl/ca-certificates-root-y.crt
onion@onion:~/onionspray$ curl https://letsencrypt.org/certs/gen-y/root-ye.pem >> projects/example/ssl/ca-certificates-root-y.crt
onion@onion:~/onionspray$ curl https://letsencrypt.org/certs/gen-y/root-yr.pem >> projects/example/ssl/ca-certificates-root-y.crt
Then edit the onionsite configuration (like example.conf), and make sure to
replace the existing nginx_proxy_ssl_trusted_certificate setting to use the
customized CA-certificates file (adapt to your case):
set nginx_proxy_ssl_trusted_certificate /home/onion/onionspray/projects/example/ssl/ca-certificates-root-y.crt
Finally, reconfigure and restart your service (again, adapt to your case):
onion@onion:~/onionspray$ ./onionspray configure example.conf
onion@onion:~/onionspray$ ./onionspray bounce example
Fix
Eventually, these root certificates will be available in the standard
ca-certificates package, so in the long run the default configuration
using /etc/ssl/certs/ca-certificates.crt can be reverted back.
Until this does not happen, the workaround above can be useful, with the caveat
of not being automatically managed, meaning that any updates in root
certificates won’t be propagated to the custom file without manual
intervention.
To ensure your onionsite proxy won’t break due to these errors, you can monitor
it’s health status using Onionprobe, which detects and reports these and
other common issues.