docs-status-codes

This repository contains the AsciiDoc and other sources to build the Status Codes for Errors & Notifications.

Installation

To build these docs locally you will need Node & NPM installed.

To install the dependencies run:

npm install

Live Preview

To preview the docs, run:

npm run start

This will build a set of HTML files in build/site and then serve them through an express server at http://localhost:8000. The start script will also listen for changes and automatically rebuild the files. You will still need to refresh the page to view the changes.

Contributing

To make changes to this repository, please create a fork of this repo and a new branch to stage your changes. Your branch should be prefixed with the version number, for example, dev-new-examples.

When you are finished with your changes push the branch to your fork and create a Pull Request. Please add at least one approver.

Guidelines for writing errors and notifications

The new errors and notifications are written in the neo4j repo and then added to this repo docs-status-codes by adding the notification or error details and examples.

General guidelines

• Use sentence case (you capitalize the first letter, proper nouns, and names, just like you would in a normal sentence) and punctuation.

• Always use present tense and active voice (when the subject of the sentence is the one doing the action, see https://www.merriam-webster.com/words-at-play/active-vs-passive-voice-difference) if possible.

• Be specific and try to use only words that count.

• Avoid repeating content from other parts, such as title, description, code, etc.

• Avoid using verbs or verb derivatives, for example, “Using”, “Running”, “The use of”, “Adding”.

• Do not use exclamation marks.

• Avoid blaming the user. Focus the message on the problem that could be fixed.

  For example, “Did not supply query with enough parameters.“ could be rewritten to “The query does not have enough parameters”.

  “You are using an experimental feature.” is another example of focusing on the user instead of what the notification is about. It could be omitted as the title already says that it is an experimental feature.

• Avoid using “please”.

• Avoid the phrase “It is recommended to” when proposing a solution.

• Capitalize all Cypher keywords, i.e., MATCH rather than match or Match.

Security guidelines for writing error messages

• Be informative but not too revealing. Error messages should provide enough information for users to understand what went wrong and possibly how to correct it, but they should not disclose sensitive information that could aid an attacker. For instance, instead of saying "Invalid username," use "Invalid username or password."

• Avoid technical jargon. Use plain language that is easily understandable by all users. Avoid technical terms that could confuse users or reveal too much about the underlying architecture.

• Use generic responses for security-related errors. For login errors, password validations, or any security-related processes, use generic error messages. For example, use "Login failed" instead of specifying whether the username or password was incorrect.

• Do not expose internal information. Never reveal information about the internal state of the application, like file paths, database information, or stack traces, as these can provide attackers with clues about potential vulnerabilities. Stack traces are safe to have in debug.log but nowhere else.

• Do not use error messages from underlying libraries/dependencies (e.g. Java runtime errors) but always catch the error and throw your own error message. It is safe to reuse error messages only if they are coming from Neo4j, i.e. have a Neo4j status code.

• Guide users towards resolution. Where appropriate, guide users on how to rectify the error. For instance, if a user inputs an invalid format in a form, the error message should indicate the expected format.

• Log detailed errors for internal use. While showing generic error messages to users, log detailed error information internally. This will help developers to debug issues without exposing sensitive information to users.

• Regularly review and update error messages to ensure they remain relevant, accurate, and secure.

Tip	Optional further reading OWASP Cheat Sheet Series: Application Logging Vocabulary Cheat Sheet OWASP Cheat Sheet Series: Logging Cheat Sheet

Error and notification components

Each error and notification comprises the following components, some of which are documented only here in this repo.

Element	More information	Notification	Error
StatusCode (Neo.[Type].[SubType].[Name])	See StatusCode syntax.	For example, Neo.ClientNotification.Statement.CartesianProduct.	For example, Neo.DatabaseError.Statement.RemoteExecutionFailed.
Notification title/ Error description (Will be removed in 6.0)	See Notification title/error description.	For example, This query builds a cartesian product between disconnected patterns.	For example, The database was unable to execute a remote part of the statement.
SeverityLevel	See Severity level.	One of INFORMATION|WARNING	ERROR
Category		One of DEPRECATION|HINT|UNSUPPORTED|UNRECOGNIZED|SECURITY|GENERIC|PERFORMANCE|TOPOLOGY|SCHEMA	N/A
Notification description (Will be removed in 6.0)	See Notification description.	Contains the main information, such as the problem, cause, consequences, and a simple solution (if possible).	N/A
Message (It will replace the notification title and description, and the error description and message in 6.0.)	See Message.	Contains the main information, such as the problem, cause, consequences, a simple solution if possible.
Example (only in the Neo4j Status Codes documentation)	See Example.	Contains one or more example queries to illustrate the possible scenarios when this notification would be returned.	N/A for 5.x
Suggestions for improvement (only in the Neo4j Status Codes documentation)	See Example.	Contains a possible solution for the provided example query.	N/A for 5.x

The following are guidelines on how to write each of the notification and error components.

StatusCode syntax

All Neo4j status codes follow the syntax Neo.[Type].[SubType].[Name].

StatusCode	Neo	[Type]	[SubType]	[Name]	Example
Notification	Neo	ClientNotification	One of Statement, Procedure, Schema, Database, Security, Cluster, or Request.	Should be specific and explains what this code refers to, e.g., ExhaustiveShortestPath.	Neo.ClientNotification.Statement.ExhaustiveShortestPath
Error	Neo	One of ClientError, TransientError, DatabaseError	One of ChangeDataCapture, Cluster, Database, Fabric (deprecated), General, Procedure, Request, Routing, Schema, Security, Statement, Transaction.	Should be specific and explains what this code refers to, e.g., RemoteExecutionFailed.	Neo.DatabaseError.Statement.RemoteExecutionFailed

Notification title/error description

The notification title and the error description contain similar information. Therefore, they follow the same guidelines. Both should be brief (one short sentence), specific, and inform on the current situation and what code of the query triggered the notification/error (add it within backticks to show that it’s a code snippet, e.g. `dbname`). Avoid explaining the cause, consequences, or solution. The notification title and description will be replaced by a single field message in 6.0. The error description in 5.x is used just as a fallback error message in some specific cases, and in 6.0, it will no longer be used. See Message.

Table 1. Examples for notification title and error description

Example	⛔ Don’t	✅ Do
Notification title 1	The provided pattern is unbounded, consider adding an upper limit to the number of node hops.	The pattern <pattern> is unbounded.
Notification title 2	The provided label is not in the database.	The label Perso does not exist.

Severity level

The severity can be one of the following:

• WARNING: It is about queries/commands that may have structural, syntactic, semantic, or spelling issues where the query most probably is wrong and/or should be updated. This includes deprecations, experimental features, trying to match entities with non-existing labels, etc. It should be clear what the problem is and it is also good to tell the possible cause, and the consequences, as well as give an example(s) and suggestion(s) for improvement. The most important part is that "we are (almost) certain it is a problem" and we know how to fix their query. For example:

  • Deprecations – The users need to update the query with new functionality.

  • Experimental features – These cannot be trusted and should be updated if used in production.

  • Non-existing label – This query will never give any result, so it’s either useless to run OR a misspelled label (unless they add a node with the label, but then the notification would disappear).

• INFORMATION: It is about queries/commands that are correct but may have some performance issues or that have no effect because they try to do something already done. Depending on the case, we may give an example(s) and suggestion(s) for improvement.

• ERROR: It is about queries/commands that fail to succeed. It’s good to tell the user what triggers the error, an example, and a possible solution(s).

Notification description

The Notification description should contain the most important information for the user. They should be brief, scannable, specific, and contain the following details (if applicable):

• Cause — what triggered the code to be returned.

• Consequences — why it might be a problem.

• A simple solution if possible.

Table 2. Examples of notification descriptions

Example	⛔ Don’t	✅ Do
Notification description 1	Using shortest path with an unbounded pattern will likely result in long execution times. It is recommended to use an upper limit to the number of node hops in your pattern.	Shortest path with an unbounded pattern may result in long execution times. Use an upper limit to the number of node hops in your pattern.
Notification description 2	Using an already bound variable for a variable length relationship is deprecated and will be removed in a future version. (the repeated variable is: r)	A variable length relationship that is bound more than once does not return any result.
Notification description 3	One of the labels in your query is not available in the database, make sure you didn’t misspell it or that the label is available when you run this statement in your application (the missing label name is: Perso)	Non-existing labels yield no result. Verify that the label is spelled correctly.

Message

In 6.0, the notifications and errors will have only a message, which will be used instead of the notification title and description, and the error description and message.

The message should follow the same guidelines as the notification description, namely:

The message should contain the most important information for the user. It should be brief, scannable, specific, and contain the following details (if applicable):

• Problem — what happened and what code of the query triggered the notification/error (add it within backticks to show that it’s a code snippet, e.g. `dbname`).

• Cause — what triggered the code to be returned.

• A simple solution if possible.

Table 3. Examples of error messages

Example	⛔ Don’t	✅ Do
Error message 1	Failed to create the specified database '%s': The total limit of databases is already reached. To create more you need to either drop databases or change the limit via the config setting 'dbms.max_databases'	Failed to create the database $param1. The limit of databases is reached. Either increase the limit using the config setting $param2 or drop a database.
Error message 2	Database does not exist. Database name: '%s'	$param database not found. Verify that the spelling is correct.
Error message 3	The allocation of an extra %s would use more than the limit %s. Currently using %s. %s threshold reached	Failed to allocate $param1. Currently using $param2`. Increase the memory pool limit using $param3.

Example

Note	This component is currently documented only for notifications. If you are updating an error, you can skip this section.

The examples and possible solutions are written only here in this repo, for the Neo4j Status Codes documentation.

Add one or more example queries to illustrate the possible scenarios when this notification would be returned. They should look similar to the following:

Example 1. <Add a caption that explains the example>

Query

Here write the query.

Description of the returned code

Same as in the neo4j repo.

Suggestions for improvement

Give a possible solution for the provided example query.

For example:

⛔ Don’t

✅ Do

Example 2. Cartesian product Query MATCH (c:Child), (p:Parent) RETURN c, p Description of the returned code If a part of a query contains multiple disconnected patterns, this will build a cartesian product between all those parts. This may produce a large amount of data and slow down query processing. While occasionally intended, it may often be possible to reformulate the query that avoids the use of this cross product, perhaps by adding a relationship between the different parts or by using OPTIONAL MATCH (identifier is: (p)) Suggestions for improvement In case a cartesian product is needed, nothing can be done to improve this query. In many cases, however, you might not need a combination of all children and parents, and that is when this query could be improved. If for example, you need the children and the children’s parents, you can improve this query by rewriting it to the following: MATCH (c:Child)-[:ChildOf]->(p:Parent) RETURN c, p

Example 3. Cartesian product Query MATCH (c:Child), (p:Parent) RETURN c, p Description of the returned code The disconnected patterns $param build a cartesian product. A cartesian product may produce a large amount of data and slow down query processing. Suggestions for improvement If you only need the children and the children’s parents, and not all combinations between them, add [:ChildOf] between the Child and the Parent nodes: MATCH (c:Child)-[:ChildOf]->(p:Parent) RETURN c, p