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 Python Driver, an error extending the neo4j.exceptions.Neo4jError class will be thrown.

Exception Types

Depending on the nature of the error, you may receive one of the following exceptions:

  • neo4j.exceptions.Neo4jError - Raised when the Cypher engine returns an error to the client.

  • neo4j.exceptions.ClientError - The Client sent a bad request - changing the request might yield a successful outcome.

    • neo4j.exceptions.CypherSyntaxError - Raised when the Cypher statement contains one or more syntax errors

    • neo4j.exceptions.CypherTypeError - Raised when or more of the data types in the query is incorrect

    • neo4j.exceptions.ConstraintError - Raised when action is rejected due to a constraint violation

    • neo4j.exceptions.AuthError - Raised when authentication failure occurs.

    • neo4j.exceptions.Forbidden - Raised when the action is forbidden for the authenticated user

  • neo4j.exceptions.TransientError - The database cannot service the request right now, retrying later might yield a successful outcome

    • neo4j.exceptions.ForbiddenOnReadOnlyDatabase - The write cypher you are requesting cannot be run on a readonly database

    • neo4j.exceptions.NotALeader - The write query cannot be executed on the current server because it is not the leader of the cluster

You can catch the specific exception above within a try/catch block, or catch all Neo4jErrors instances:

# Import the Exception classes from neo4j.exceptions
from neo4j.exceptions import Neo4jError, ConstraintError

# Attempt a query
    tx.run(cypher, params)
except ConstraintError as err:
    print("Handle constaint violation")
    print(err.code) # (1)
    print(err.message) # (2)
except Neo4jError as err:
    print("Handle generic Neo4j Error")
    print(err.code) # (1)
    print(err.message) # (2)

Exceptions contain code (1) and message (2) properties to help you further diagnose the problem.

Error Codes

The Neo4jError 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.

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

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 detail 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 Python 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.


Hi, I am an Educational Learning Assistant for Intelligent Network Exploration. You can call me E.L.A.I.N.E.

How can I help you today?