Handling Driver Errors

When executing a Cypher statement, certain exceptions and error cases may arise. One error could be a transient error that may be resolved if retried, for example a problem connecting to the database instance. Another type of error could be something more permanent, for example a Syntax Error or a Constraint Error.

In the Neo4j JavaScript Driver, the Promise returned by the run() method will be rejected, and an instance of a Neo4jError will be returned.

The Neo4jError class extends the native JavaScript Error, and as such contains a message property that contains detailed information about the error that has occurred.

Error Codes

The Neo4jError also includes a code property, which provides higher-level information about the query.

Each status code follows the same format, and includes four parts:

(1)        (2)          (3)       (4)
  1. Every Neo4j Error code is prefixed with Neo.

  2. The Classification provides a high-level classification of the error - for example, a client-side error or an error with the database.

  3. The Category provides a higher-level category for the error - for example, a problem with clustering, a procedure or the database schema.

  4. The Title provides specific information about the error that has occurred.

Example Error Codes

Here are some common error codes that you may experience:

  • Neo.ClientError.Procedure.ProcedureCallFailed - Failed to invoke a procedure. See the detailed error description for exact cause.

  • Neo.ClientError.Schema.ConstraintViolation - Added or changed index entry would violate constraint.

  • Neo.ClientError.Security.Forbidden - An attempt was made to perform an unauthorized action.

  • Neo.ClientError.Security.Unauthorized - The client is unauthorized due to authentication failure.

  • Neo.ClientError.Statement.ParameterMissing - The statement refers to a parameter that was not provided in the request.

  • Neo.ClientError.Statement.SyntaxError - The statement contains invalid or unsupported syntax.

  • Neo.TransientError.General.TransactionMemoryLimit - There is not enough memory to perform the current task.

For a comprehensive list of status codes, see Status Codes in the Neo4j Documentation.

Catching Errors

Below are examples of how to catch an error thrown by the Driver using both async/await and the Promise API.

Example 1. Using async/await

When using async/await, you will need to use try and catch blocks to catch any errors.

Async Example
Unresolved directive in lesson.adoc - include::https://raw.githubusercontent.com/neo4j-graphacademy/llm-vectors-unstructured/main/example/catch-errors.js[tag=catch]
Example 2. Using Promises

When using Promises, you will need to add a catch() function to catch any errors.

Using Promises
Unresolved directive in lesson.adoc - include::https://raw.githubusercontent.com/neo4j-graphacademy/llm-vectors-unstructured/main/example/catch-errors.js[tag=promise]

Check Your Understanding

1. Which property is appended to the Neo4jError object to provide a generic overview of the error message?

  • error.code

  • error.description


Neo4j errors include a code property, which provides higher-level information about the query.


To access the error code, you should use the error.code property.

2. Which property can we examine to find detailed information about any error thrown by the driver?

  • error.code

  • error.description

  • error.message


Neo4j errors include a message property, which provides more detailed information about the error.


To access the detailed error message, you should use the error.message property.

Lesson Summary

In this lesson, you have learned how to interpret the errors thrown by the Neo4j JavaScript Driver.

In the next Challenge, you will add a unique constraint to the database and add a try/catch block the register() method to handle the error thrown when the email address is already taken.