Translation of Unhelpful Neo4j Error Messages

Neo4j is an open-source graph database developed in Java, and is one of the many popular NoSQL databases. Neo4j stores data in nodes connected by directed, typed relationships with properties on both, also known as a Property Graph. Cypher is the declarative query language used by Neo4j for traversing the graph and creating and updating nodes.

Neo4j is a quite interesting and promising technology for relational data storage. However, possibly due to its young age and small community, many of the error messages Neo4j and Cypher provide can be quite cryptic and unhelpful. I've assembled a small collection of such error messages and attempted to give them a bit of meaning through explanation and example.

CypherTypeException: Collections containing mixed types can not be stored in properties.
The most likely explanation is that there was an array used in a Cypher query somewhere that has more than one data type contained in its values. For example:

START n=node:listing(id='test.id') SET n.list = [1, 2, 3, 'a', 5];

The only solution here is to just ensure that all values in your array are of the same type.

TransactionFailureException: Unable to commit transaction
The most common time you'll see this extremely vague message is when attempting to delete a node. This error typically appears when the node you're attempting to delete still has relationships. For example:

Performing the Cypher query in this way will ensure that all relationships between 'content' and any other nodes will be removed before attempting to remove the 'content' node.

SyntaxException: Unknown identifier `<whatever>`
What it most likely means is that you referenced a node or property that doesn't exist or isn't available within the scope of your query, and this case is relatively straight-forward. However, this can also occur sometimes when an argument used in the ORDER BY clause is not part of the return set of the query. Here is an example: (note, this Cypher query was invented for illustration purposes, but is not based on an actual system, so I can't guarantee it makes practical sense)

To fix the problem, just add article.releaseDate to the set of return values in the Cypher query.

ThisShouldNotHappenError: Developer: Andres claims that: Aggregations should not be used like this
This one is probably one of the strangest error messages I've ever received. Andres is the creator of Cypher, and basically the error means you should not use ORDER BY with aggregations. The workaround for this is introducing another WITH that does aggregation and aliasing and use the aliased name in ORDER BY. Here is an example: (note, this Cypher query was invented for illustration purposes, but is not based on an actual system, so I can't guarantee it makes practical sense)

UniquePathNotUniqueException: The pattern exampleProperty-[:`IS_A`]->articles_root produced multiple possible paths, and that is not allowed
A particular entry in the index somehow exists multiple times (in my experience, this seems to randomly happen sometimes; probably from poor coding), so Neo4j couldn't find a unique path between node A and node B. The solution is to lookup in the index the particular node you're attempting to modify to identify duplicates, and remove all of them except for one.

InternalException: Expected to be in a transaction but wasn't
This fairly vague error message seems to appear randomly when attempting to perform write actions, and it means that somehow the query was executed outside of a transaction. This can occur when, for whatever reason, the OS fails to write to the disk. Since the database is unable to know what has been written and what has not it has to abort its operations. This seems to happen a few times per year in my experience. When you encounter an error like this the only way I've found to recover is to just restart Neo4j.

In newer versions of Neo4j (i.e. 1.9.x) this error should occur less often since the database will attempt a recovery automatically. When it is able to recover, it will behave the same as if the user had restarted the database. Requests that come into the database during recovery will queue up and be handled once the database is back in a safe state, assuming the issue with writing to disk is resolved. If the database continues to be unable to talk to the harddrive, it will shut down.

Error Message: In neo4j/data/graph.db/messages.log (Note: there should be three Neo4j servers in this cluster):

When you see something like this it could indicate that there is something wrong with the neo4j/data/coordinator/myid file. This file should contain a unique node id on each server, but from the log shown above, it indicates that neo4j-server01.my.network and neo4j-server03.my.network have the same value in the myid file or in neo4j.properties. The first thing to attempt is to correct the values in myid (if they're wrong) and to check the value of ha.serverId in neo4j.properties. Once you've corrected those and restarted neo4j and neo4j-coordinator, if you still have a problem you may need to purge the state in zookeeper (i.e. the neo4j-coordinator):

1) Shut down all slaves (neo4j/bin/neo4j stop)
2) Shut down master
3) Shut down all zookeeper instances (neo4j/bin/neo4j-coordinator stop)
4) Remove neo4j/data/coordinator/version-2/* from all cluster members, but make sure you don't remove the myid file
5) Verify that the myid file is different on all nodes
6) Start up zookeepers (neo4j/bin/neo4j-coordinator start) on all instances
7) Start up master (neo4j/bin/neo4j start)
8) Start up slaves

Most of my experience to this point has been with Neo4j 1.8 and 1.8.3. I've attempted to upgrade to 1.9.2, but for whatever reason many queries that previously functioned properly would take 20 or more minutes to return a result, so I gave up with the newer version. However, from my research it seems likely that the newer versions of Neo4j should be more stable and somewhat less prone to unusual errors.

IllegalProtocolVersionException and ComException
I once encountered an odd and random problem where one of the nodes in my cluster (specifically node #2) had its log file fill up to 31GB with:

I still have no idea what this should mean, but in an attempt to recover, I shut down all nodes and and all neo4j-coordinator instances and restarted them one-by-one. The node with the problem, node 2, still had the error, but now suddenly node 3 also had problems:

Even with node2 shut down and completely removed from the cluster the error still persisted.

The solution to this problem was to change which server is used for moderating the communication between the different nodes (which in my case was node02.mysite.com). To change this, edit conf/neo4j.properties:

About

Valhalla is a place for sharing knowledge and ideas. Users can submit code, as well as science, technology, and engineering-oriented news and articles. We also have an assortment of fun and educational challenges intended to help users learn more about programming, mathematics, encryption, hacking and more.

We also affiliate with other IT-related sites. We provide a biography and tags for each affiliate so users can easily find the content they are interested in.