This repository contains the AsciiDoc and other sources to build the Status Codes for Errors & Notifications.
To build these docs locally you will need Node & NPM installed.
To install the dependencies run:
npm installTo preview the docs, run:
npm run startThis 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.
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.
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.
-
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.,
MATCHrather thanmatchorMatch.
-
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
|
Each error and notification comprises the following components, some of which are documented only here in this repo.
| Element | More information | Notification | Error |
|---|---|---|---|
StatusCode ( |
See StatusCode syntax. |
For example, |
For example, |
Notification title/ Error description (Will be removed in 6.0) |
For example, |
For example, |
|
SeverityLevel |
See Severity level. |
One of |
|
Category |
One of |
N/A |
|
Notification description (Will be removed in 6.0) |
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.
All Neo4j status codes follow the syntax Neo.[Type].[SubType].[Name].
| StatusCode | Neo |
[Type] |
[SubType] |
[Name] |
Example |
|---|---|---|---|---|---|
Notification |
|
|
One of |
Should be specific and explains what this code refers to, e.g., |
|
Error |
|
One of |
One of |
Should be specific and explains what this code refers to, e.g., |
|
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.
| 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 |
Notification title 2 |
The provided label is not in the database. |
The label |
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).
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.
| 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. |
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.
| 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 |
Error message 2 |
Database does not exist. Database name: '%s' |
|
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 |
|
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:
- Query
-
Here write the query.
- Description of the returned code
-
Same as in the
neo4jrepo. - Suggestions for improvement
-
Give a possible solution for the provided example query.
For example:
| ⛔ Don’t | ✅ Do |
|---|---|
Example 2. Cartesian product
|
Example 3. Cartesian product
MATCH (c:Child)-[:ChildOf]->(p:Parent) RETURN c, p |