Skip to content

Add a GQLSTATUS code to the current errors #176

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Add a GQLSTATUS code to the current errors #176

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 90 additions & 10 deletions modules/ROOT/pages/errors/all-errors.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,29 +1,109 @@
:description: The Neo4j error codes for Neo4j version {neo4j-version}.


[[neo4j-errors]]
= List of all server error codes
= List of all Neo4j 5 server error codes

Error codes are Neo4j status codes returned by the server when the execution of a query fails.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is always hard with naming, but I wonder if 'error codes' is too unspecific here? The new GQLSTATUS codes are also a type of error codes is my thinking.

Maybe the other way around i.e. that we call the section
'List of all Neo4j 5 status codes' and rewrite this sentence to 'Neo4j status codes are error codes returned by the server...'. Let me know what you think

Copy link
Collaborator Author

@renetapopova renetapopova Sep 13, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I somehow needed to differentiate between both pages. We'll have another page about the GQLSTATUS codes. So, in the end, the structure will be something similar to:

  • Server errors
    • List of all Neo4j 5 server error codes
    • List of all GQLSTATUS server error codes
  • Server notifications

They always have the severity level `ERROR`.
Errors are grouped based on the type of the error code:

Client errors::
These errors are caused by the client and are usually related to the request itself.
Client errors have the prefix `Neo.ClientError`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know this is just moved text, but we could maybe clarify it by writing 'Neo4j status codes for client errors have the prefix Neo.ClientError'. Same for transient errors and database errors too

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure what you're suggesting. The whole page is about Neo4j status codes only.


Transient errors::
These errors are detected by the server and are usually related to some kind of database unavailability, such as limits reached, out-of-memory, timeouts, etc.
The error can be temporary and could therefore succeed if retrying the request.
Transient errors have the prefix `Neo.TransientError`.

Database errors::
These errors are caused by the database and are usually related to the database state.
Database errors have the prefix `Neo.DatabaseError`.

This page contains lists of all Neo4j errors, grouped by type.

[[neo4j-client-errors]]
== Client errors

This is a complete list of all client errors Neo4j may return, and what they mean.

[[Neo.ClientError.ChangeDataCapture.InvalidIdentifier]]
=== `Neo.ClientError.ChangeDataCapture.InvalidIdentifier`

This error occurs when the given change identifier is invalid.

.Error details
[cols="<1s,<4"]
|===
|Description
a| Invalid change identifier.
|GQLSTATUS code(s)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should clarify that this is a cause GQLSTATUS code in some way. In the next table you have the top level code in the same place and that distinction would be important to know for someone adapting their code to the new system

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, this shouldn't be the cause code. This is the top-level code.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I used the spreadsheet https://docs.google.com/spreadsheets/d/1VNF5uO3LfoUGYQkewAA7H3IoNmXNmhSZlUOf3EIvfUw/edit?gid=1522141749#gid=1522141749

m|52N16
| Returned message(s)
a|
[options="header", cols="<4,<1"]
!===
! Message ! GQLSTATUS code
! Invalid change identifier. ! 52N26
! Given change identifier does not belong to this database ! 52N31
! Given ChangeIdentifier describes a transaction that hasn't yet occurred ! 52N30
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When I look at the CDC tab in the Error spreadsheet the one listed as 52N30 here (CDC-005) is actually 52N32 (although it has an old comment from me and the same old message as CDC-001 which is 52N30). Also CDC-004 seems to be missing.

I am not sure which source you have used for the table, so it can be either a misstake there or by you. The rest of the codes in this table look correct

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we are seeing different things in the spreadsheet. This is what I see for 52N16:

Screenshot 2024-09-13 at 12 09 25

! Unable to find the transaction entry for the given change identifier ! 52N28
!Given ChangeIdentifier describes a transaction that occurred before any enrichment records exist ! 52N29
!===
|===

[[Neo.ClientError.Cluster.NotALeader]]
=== `Neo.ClientError.Cluster.NotALeader`

This error occurs when the request cannot be processed by this server.
Write requests can only be processed by the leader.

.Error details
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe that is because this is just a first draft, but the messages below are only a subset of the ones for Neo.ClientError.Cluster.NotALeader

[cols="<1s,<4"]
|===
|Description
a| The request cannot be processed by this server. Write requests can only be processed by the leader.
|GQLSTATUS code(s)
m|08N07
| Returned message(s)
a|
[options="header", cols="<4,<1"]
!===
! Message ! GQLSTATUS code
! Failed to acquire lease since it was taken by another candidate!08N07
! Local instance lost lease. !08N07
! Should only attempt to acquire lease when leader. !08N07
!===
|===


[[Neo.ClientError.Cluster.Routing]]
=== `Neo.ClientError.Cluster.Routing`

This error occurs when the request cannot be routed to the appropriate server.

.Error details
[cols="<1s,<4"]
|===
|Description
a| Unable to route the request to the appropriate server
|GQLSTATUS code(s)
m|08N02
| Returned message(s)
a|Unable to route to database `$dbName`. Server-side routing is disabled. Either connect to the database directly using the driver (or interactively with the :use command), or enable server-side routing by setting `$routingEnabledSetting=true`.
|===

//================================================================
// Current list of all errors to be used as a reference
[options="header", cols="<1m,<1"]
|===
| Neo4j status code
| Description
| Neo.ClientError.ChangeDataCapture.InvalidIdentifier
| Invalid change identifier.

| Neo.ClientError.Cluster.NotALeader
| The request cannot be processed by this server. Write requests can only be processed by the leader.

| Neo.ClientError.Cluster.Routing
| Unable to route the request to the appropriate server
|
|
| Neo.ClientError.Database.DatabaseNotFound
| The request referred to a database that does not exist.
Expand Down
16 changes: 1 addition & 15 deletions modules/ROOT/pages/errors/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,18 +4,4 @@
= Server errors
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suppose we might also want to rewrite the rest of the text here a bit and turn this into more of an overview page? That can be a separate PR though


Error codes are Neo4j status codes returned by the server when the execution of a query fails.
They always have the severity level `ERROR`.
Errors are grouped based on the type of the error code:

Client errors::
These errors are caused by the client and are usually related to the request itself.
Client errors have the prefix `Neo.ClientError`.

Transient errors::
These errors are detected by the server and are usually related to some kind of database unavailability, such as limits reached, out-of-memory, timeouts, etc.
The error can be temporary and could therefore succeed if retrying the request.
Transient errors have the prefix `Neo.TransientError`.

Database errors::
These errors are caused by the database and are usually related to the database state.
Database errors have the prefix `Neo.DatabaseError`.
They always have the severity level `ERROR`.