GraphAcademy

Building Neo4j Applications with Node.js

Project Introduction

The Neo4j JavaScript Driver

Interacting with Neo4j

Homework: Project Backlog

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:

Neo.[Classification].[Category].[Title]
(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.

Learn how to interact with Neo4j from Node.js using the Neo4j JavaScript DriverUsing async/await

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

js
Async Example
// Open the session
const session = this.driver.session()

try {
  // Run the query...
  const res = await session.executeWrite(tx => tx.run(`
    CREATE (:User {email: $email})
  `, { email: 'uniqueconstraint@example.com' }))

  // The query ran successfully
  console.log(res.records[0])
}
catch (e) {
  if (e.code === 'Neo.ClientError.Schema.ConstraintValidationFailed') {
    console.log(e.message) // Node(33880) already exists with...

    throw new ValidationError(`An account already exists with the email address ${email}`, {
      email: e.message
    })
  }

  throw e
}
finally {
  // Finally, close the session
  await session.close()
}
Learn how to interact with Neo4j from Node.js using the Neo4j JavaScript DriverUsing Promises

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

js
Using Promises
// Run the query...
session.executeWrite(tx => tx.run(`
  CREATE (:User {email: $email})
`, { email: 'uniqueconstraint@example.com' }))
  .then(res => {
    // The query ran successfully
    console.log(res.records[0])
  })
  .catch(e => {
    // An error has occurred
    if (e.code === 'Neo.ClientError.Schema.ConstraintValidationFailed') {
      console.log(e.message) // Node(33880) already exists with...

      throw new ValidationError(`An account already exists with the email address ${email}`, {
        email: e.message
      })
    }

    throw e
  })
  .finally(() => {
    // Finally, close the session
    return session.close()
  })

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

Hint

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

Solution

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

Hint

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

Solution

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.