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:
START x = node(123) MATCH x-[r?:RELATED_CONTENT]->content WHERE content.source='user' DELETE r, content
If 'content' still has relationships then the Neo4j shell will state that it was unable to commit this transaction. Here's how you can accomplish your delete:
START x = node(123) MATCH x-[r?:RELATED_CONTENT]->content WHERE content.source='user' WITH content MATCH content-[r1?]-() DELETE r1, content
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)
START source=node:root("source:user") MATCH source<-[:IS_A]-(author)<-[r:ARTICLE_RELATEDTO_AUTHOR]-article, WITH author, article, r WHERE article.rating > 3 RETURN article.id, ORDER BY article.releaseDate DESC SKIP 10 LIMIT 20
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)
START source=node:root("source:user") MATCH source<-[:IS_A]-(author)<-[r:ARTICLE_RELATEDTO_AUTHOR]-article, WITH author, article, r WHERE article.rating > 3 RETURN article.id, collect(article.releaseDate?) AS articleReleaseDate, max(article.releaseDate) ORDER BY max(article.releaseDate) DESC SKIP 10 LIMIT 20
To make this query work you have to perform the aggregation at some point before the ORDER BY. For example:
START source=node:root("source:user") MATCH source<-[:IS_A]-(author)<-[r:ARTICLE_RELATEDTO_AUTHOR]-article, WITH author, article, r WHERE article.rating > 3 WITH max(article.releaseDate) AS maxReleaseDate, article RETURN article.id, collect(article.releaseDate?) AS articleReleaseDate, maxReleaseDate ORDER BY maxReleaseDate DESC SKIP 10 LIMIT 20
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):
2012-3-25 14:12:57,436 INFO [neo4j]: Read HA server:neo4j-server01.my.network:6001 (for machineID 3) from zoo keeper 2012-3-25 14:12:57,438 INFO [neo4j]: Read HA server:neo4j-server02.my.network:6001 (for machineID 2) from zoo keeper 2012-3-25 14:12:57,440 INFO [neo4j]: Read HA server:neo4j-server01.my.network:6001 (for machineID 1) from zoo keeper 2012-3-25 14:12:57,442 INFO [neo4j]: Checking compatibility mode, read 3 as all machines, 3 as myVersion machines. Based on that I return false
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:
org.neo4j.com.IllegalProtocolVersionException: Got wrong protocol version during newMaster, expected 4 but got 1
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:
ERROR [neo4j]: Communication exception in newMaster, retry #1 org.neo4j.com.ComException: Client could not connect to node02.mysite.com/192.168.1.20:6001
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:
Image from NeoTechnology