When integrating Neo4j with other Third Party products, it is perhaps not always clear as to which product the issue is originating from. The below scenarios have been provided along with tips to help users triage to determine the best direction to start troubleshooting. In addition, the outcome of the initial troubleshooting steps can also be added to a support case to help speed up resolution of any Neo4j reported issues. (Note: This knowledge article is intended to be a living document that will be continuously updated as new scenarios are identified so please continue to revisit for updated content. In addition, the documentation links provided are based on the latest Neo4j version - if using an older supported version, ensure to change the referenced links to the appropriate version of documentation.)

LDAP Connection Issues

SSL Connection Issues

SSO Connection Issues using OpenID Connect Identity Provider

External Application Connection Issues

External Application Produces Unexpected Query Results

Custom Application code issues

 

LDAP Connection Issues:

1. Can the LDAP connection be established from the server using ldap-search outside the application? If not, contact the customer site LDAP administrator to help troubleshoot further to ensure a working connection outside of Neo4j as the first step.

NOTE: The working ldap-search string and results can be used to help configure the neo4j.conf file and should be provided to Neo4j support if further assistance as needed.

 

SSL Connection Issues:

1. Ensure valid certificates have been created/received from your organization and are present on the server. Neo4j support does not provide SSL certificates used for the Neo4j environment. Certificates should be requested internally at the customer site as needed and would be required before any troubleshooting can begin.

 

SSO Connection Issues:

1. SSO configuration in Neo4j is based on the Configuration of the OIDC provider for the application. The customer site SSO Administrator should provide the configuration needed for which can then be configured in the neo4j.conf file.
2. A good resource for reference is the tutorial-sso-configuration section of documentation. This can be reviewed based on the identity provider for proper configuration and troubleshooting steps in addition to the SSO documentation in the Operations Manual.
3. Additional logging can be enabled to check the JWT claim coming back to Neo4j from the OIDC provider token (see SSO debug jwt claim logging )

NOTE: The JWT claim logging showing the token information (or the token information from the browser in older versions) should be provided along with the neo4j.conf and security.log for additional troubleshooting help when opening a support case.

 

External Application Connection Issues to Neo4j:

1. Can the connection via cypher-shell and to the Neo4j Browser be established successfully to verify that the connection issue still exists only with the external application?
2. Can the client machine establish connection to the Neo4j server machine and  from the server back to client over the network to verify that there are no layers blocking? 

NOTE: If after completing these checks the issue persists, capture details on how the application is connecting along with the code/configuration being used. (i.e. Connector and version in use, driver and version in use, driver code snippet used to create the connection, etc.) Also note the full error that is seen on the connection attempt and provide this information in a new support case for further investigation.  See the section for Custom application code issues as well.

 

External Application Produces Unexpected Query Results:

1. Are the same unexpected results produced if connecting via the Neo4j browser and cypher-shell directly? This will help to eliminate the possibility that something in the external application may be triggering the issue.
2. If connecting via the Neo4j browser and cypher-shell produces the correct results, it is suggested to investigate the External application code and usage further.

NOTE: If the results are still unexpected connecting directly to Neo4j (eliminating the external application), capture the query as well as the returned results or error from the execution attempt. In addition, please note the expected results and provide in the support case for further review.

 

Custom Application Code Issues:

Debugging custom code is out of scope for Neo4j Technical Support. However, Neo4j provides supported drivers, libraries, and connectors that are used in custom code. When reporting issues in these areas, a working sample test code snippet to demonstrate the reported issue should be provided along with the associated logging to Neo4j support.

For example, for a suspected driver issue:

1. Create a small sample script using the suspected driver apis to recreate the issue capturing the client driver debug level logging.
2. Include the following in the support case when reporting issue:
   • driver in use
   • driver version
   • neo4j version
   • sample script
   • client side debug level logging for the example
   • server side debug level logging for the example

It is suggested to review the Neo4j Driver Best Practices here as well.