Troubleshooting Connection issues with Halin

[david_allen]

This post describes common issues users may encounter in connecting Halin to a Neo4j database, and how to address them.

Prerequisites

Halin is a JavaScript application that executes inside of your browser, and uses the Neo4j Official JavaScript driver to communicate via the bolt protocol with your database. In other words, Halin is just a javascript client of a Neo4j database, but there are some special considerations because it runs in the browser, and is subject to the browser's security model.

If this article does not solve your issue, make sure also to check out Troubleshooting Connection Issues to Neo4j, which is intended for similar issues.

Important: How are you running Halin?

Users can run halin via https://halin.graphapp.io as a web page, they can run it as a graph app in Neo4j Desktop, or on their own inside of a company. How Halin is running for you has some consequences to how you connect to Neo4j, because of the browser security model.

• Via https://halin.graphapp.io, you are on a secure SSL website with a signed certificate. This means that the browser will not permit insecure connections to 3rd party sites, or connections to other sites with self-signed certificates
• Via Neo4j Desktop, Halin is effectively running off of files loaded from your local disk, and so the HTTPs issues above don't apply.

Which IP Addresses / Hostnames can Halin See?

Because Halin runs in your browser, it can see any hostname or IP address that your machine (where you are running Halin) can reach. As a result, you can use the hostname "localhost" to refer to your local machine (for example if you are running a Neo4j Desktop instance), or if you are running Halin behind a corporate firewall, you can use an internal hostname such as neo4j.dev.intranet so long as your machine could normally connect to that address.

Encrypted vs. Unencrypted Connections

Halin will ask you to select whether or not to encrypt the connection. This is an important choice.

• Unencrypted communications may bypass any SSL issues you may have, but will have the negative that you'll be sending your username/password in cleartext over the network
• Encrypted connections are more secure, and recommended, but generally require that you have a valid SSL certificate for your Neo4j instance.

An important note is that the server must be willing to accept either encrypted or unencrypted bolt that your Halin connection is requesting. This interacts with Neo4j's dbms.connector.bolt.tls_level setting. Make sure to check those docs for further information.

WebSocket Connection Error

These connection errors look something like this:

This error can have many different causes and resolutions unfortunately.

The main way users run into this is when they check the "Encrypted" box when connecting to a local Neo4j Desktop instance.

Potential causes:

• Using the Halin website to try and connect "encrypted" to a Neo4j instance that has a self-signed SSL certificate. This won't work, because the browser's security model is blocking connection attempts to an "insecure domain" (the Neo4j self-signed host) from a "secure domain" (the halin website, which has a valid SSL cert). Resolution: get a signed certificate for your Neo4j instance (instructions), or connect unencrypted.
• Trying to connect unencrypted to an instance where the database is configured with dbms.connector.bolt.tls_level=REQUIRED. The database simply will not accept unencrypted connection requests.