After migrating or deploying new Neo4j Java environments, or switching between Java versions, client applications may fail to establish secure connections with the Neo4j server, when encrypted connections are required by the neo4j bolt connector TLS configuration.

It often helps to obtain a detailed stacktrace of the connection attempt, both client-side and server-side, which may reveal further insight regarding cause.

When encrypting using SSL/TLS certificates, enhanced server-side logging can be achieved by adding the following configuration to the neo4j configuration file ($NEO4J_HOME/conf/neo4j.conf):

server.jvm.additional=-Djavax.net.debug=ssl:handshake

Note that this configuration requires a neo4j restart to take effect. Further configuration details are documented here. Additional settings to make the stacktrace more clear:

server.jvm.additional=-Djavax.net.debug=ssl
server.jvm.additional=-Djavax.net.debug=ssl:handshake:verbose:keymanager:trustmanager
server.jvm.additional=-Djava.security.debug=access:stack

Note: The "server.jvm.additional" setting name is applicable only to Neo4j 5.x.
In Neo4j 4.x, the configuration setting is instead named "dbms.jvm.additional".

Resulting stacktraces are normally included in the neo4j.log file at $NEO4J_HOME/logs/neo4j.log.

On the Java client side (different for other drivers), for example on cypher-shell, additional stacktrace for connection attempts can be obtained by including the --debug option within the connection string. For encrypted connections, the --encryption=true option may also be specified, however, by default, its value will follow the protocol URI context used (e.g. bolt+s://, neo4j+s://, etc). Further information regarding connection URIs is available here.

In certain instances, the client-side stacktrace might reveal an error similar to the following:

sun.security.validator.ValidatorException: PKIX path building failed:
sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

Above indicates a missing certificate for the client Java application (such as Neo4j cypher-shell) within the Java truststore file. By default, the truststore file is located at $JAVA_HOME\lib\security\cacerts.

If the truststore is not in the default location, locate the current running java machine with this command:

/usr/libexec/java_home

Navigate to the current java library and locate the cacerts file with this command:

find . -name cacerts

It is useful to initially list all the certificates already present within the truststore, eg. as:

keytool -list -keystore <cacert path>

 

If the relevant public certificate is missing, it can for example be downloaded via a browser such as Chrome as shown in the example below:
 

   

Select the Export option above which should allow the certificate to be downloaded. Once downloaded, the public certificate can be added to the Java truststore using the keytool command e.g. as:

keytool -import -trustcacerts -alias <whatever name> -file <path to cert> -keystore <cacerts path> -storepass <password>

Example:

keytool -import -trustcacerts -alias myAlias -file /path/to/my/cert/myCert.cer -keystore /path/to/my/jdk/jre/lib/security/cacerts/keystore.jks -storepass changeit

Note that "changeit" is the default password for the truststore, unless otherwise set. 

The Java client connection might then be reattempted to see if the issue was resolved.

Further information on importing the certificate to the truststore is available here.