Skip to content

Update troubleshooting-runners.md #1687

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
fdevans merged 1 commit into from
Aug 7, 2025
Merged

Update troubleshooting-runners.md #1687

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions docs/administration/runner/runner-troubleshooting/troubleshooting-runners.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,47 @@
## Runner Logs

Runner Logs are located in the `./runner/logs` folder under the folder where the jar was executed from. The `runner.log` file contains operational and important messages about the runner. `operations.log` tracks an operation starts and if it succeeds or fails. [Read more about logging and setting up custom logging](/administration/runner/runner-management/runner-logging.md).

## SSL Handshake error on the Runner startup

### **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
Copy link

Copilot AI Aug 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copilot generated this review using guidance from repository custom instructions.
```

### Why does this happen?

- The RBA-SH cluster is using a certificate that is **not trusted** by the default Java truststore (e.g., self-signed, or signed by a private/internal CA). In other words, the certificate chain can’t be validated using the Java truststore.

- The Runner (Java process) doesn’t have the CA certificate in its 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.


### How to fix it

1. Download the certificate chain from your Rundeck cluster

2. Transfer this file to your Runner VM

3. Import the CA cert into the Java truststore


The default truststore is usually at:
`$JAVA_HOME/lib/security/cacerts`
The default password is `changeit`.

**Please confirm that** `$JAVA_HOME` **is correctly configured in your VM!**

Example command:

```
keytool -import -alias rundeck-ca -file /path/to/ca.crt -keystore $JAVA_HOME/lib/security/cacerts
Copy link

Copilot AI Aug 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The code block should specify 'bash' for proper syntax highlighting and include the missing closing backticks on line 42.

Copilot generated this review using guidance from repository custom instructions.
```

- It will prompt for the password (`changeit` by default).

- Say “yes” to trust the certificate.


4. Restart the Runner service.
Loading