GraphAcademy

Using Neo4j with Python

The Driver

Handling results

Best practices

Handling Database Errors

Error Handling

When working with Neo4j, you may encounter various database errors that need to be handled gracefully in your application. The driver exports a Neo4jError class that is inherited by all exceptions thrown by the database. Exceptions related to the driver and its connection are subclasses of DriverError.

Common exceptions

  • CypherSyntaxError - Raised when the Cypher syntax is invalid

  • ConstraintError - Raised when a constraint unique or other is violated

  • AuthError - Raised when authentication fails

  • TransientError - Raised when the database is not accessible

Handling errors

Any errors raised by the driver will have code and message properties that describe the error.

python
from neo4j.exceptions import Neo4jError

try:
    # Run a Cypher statement
except Neo4jError as e:
    print(e.code)
    print(e.message)
    print(e.gql_status)

The gql_status property contains an error code that corresponds to an error in the ISO GQL standard.

A full list of error codes can be found in Status Codes for Errors & Notifications.

Example: Handling unique constraint violations

One common scenario is dealing with constraint violations when inserting data. A unique constraint ensures that a property value is unique across all nodes with a specific label.

The following Cypher statement creates a unique constraint named unique_email to ensure that the email property is unique for the User label:

cypher
CREATE CONSTRAINT unique_email IF NOT EXISTS
FOR (u:User) REQUIRE u.email IS UNIQUE

If a Cypher statement violates this constraint, Neo4j will raise a ConstraintError.

Here’s an example of how to handle a unique constraint violation when creating a new user:

python
from neo4j.exceptions import ConstraintError

def create_user(tx, name, email):
    try:
        result = tx.run("""
            CREATE (u:User {name: $name, email: $email})
            RETURN u
        """, name=name, email=email)

    except ConstraintError as e:
        print(e.code)
        # Neo.ClientError.Schema.ConstraintValidationFailed
        print(e.message)
        # The value [email] for property [email] violates the constraint [unique_email]
        print(e.gql_status) # 22N41

Advance to challenge

Summary

Proper error handling is crucial for building robust Neo4j applications. By catching and handling specific exceptions:

  • Your application can gracefully handle expected error conditions

  • Users receive meaningful feedback

  • You can implement appropriate recovery strategies

  • Your application remains stable even when errors occur

Best Practices

  • Always catch specific exceptions rather than using a bare except

  • Log errors appropriately for debugging

  • Provide meaningful feedback to users

  • Consider implementing retry logic for transient errors

You can find a full list of driver exceptions in the Neo4j Python Driver Manual.

In the next challenge, you will use this information to handle errors in a real-world scenario.