Update troubleshooting-runners.md#1687
Conversation
Adding instructions on how to fix SSL Handshake error on the Runner startup.
There was a problem hiding this comment.
Pull Request Overview
This PR adds troubleshooting documentation for SSL handshake errors that occur during Runner startup. The new section provides administrators with a comprehensive guide to diagnose and resolve certificate trust issues between Runners and Rundeck clusters.
Key changes:
- Added a new troubleshooting section for SSL handshake errors
- Included error message examples, root cause explanations, and step-by-step resolution instructions
- Provided practical keytool commands for importing certificates into Java truststore
Comments suppressed due to low confidence (1)
docs/administration/runner/runner-troubleshooting/troubleshooting-runners.md:20
- [nitpick] The tone is too informal for technical documentation. Consider rephrasing to: 'This commonly occurs with internal CAs or self-signed certificates when administrators add them to the OS trust store but not to Java's truststore.'
- This is super common with **internal CAs** or **self-signed certs**—admins often add these to the OS trust store, but forget about Java’s.
|
|
||
| ### **Error message** | ||
| ``` | ||
| 08-06-2025 14:23:47.445 [main] ERROR io.micronaut.retry.intercept.RecoveryInterceptor - Type [com.rundeck.sidecar.agent.server.RESClient$Intercepted] executed with error: javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target reactor.core.Exceptions$ReactiveException: javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target |
There was a problem hiding this comment.
The error message example should use a generic date rather than a specific future date (08-06-2025). Consider using a placeholder like 'YYYY-MM-DD' or a past date to avoid confusion and maintain documentation longevity.
| Example command: | ||
|
|
||
| ``` | ||
| keytool -import -alias rundeck-ca -file /path/to/ca.crt -keystore $JAVA_HOME/lib/security/cacerts |
There was a problem hiding this comment.
The code block should specify 'bash' for proper syntax highlighting and include the missing closing backticks on line 42.
Adding instructions on how to fix SSL Handshake error on the Runner startup.