Skip to content
Open
Show file tree
Hide file tree
Changes from 1 commit
Commits
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
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
:description: This section describes how to manage errors that you may encounter while managing databases.
:page-aliases: manage-databases/errors.adoc
[role=enterprise-edition]
[[manage-database-errors]]
= Error handling

Expand All @@ -11,8 +12,9 @@ When running the database management queries, such as `CREATE DATABASE`, it is p
Because database management operations are performed asynchronously, these errors may not be returned immediately upon query execution.
Instead, you must monitor the output from the `SHOW DATABASE` command; particularly the `statusMessage` and `currentStatus` columns.

.Fail to create a database
====
=== Fail to create a database


[source, cypher]
----
neo4j@system> CREATE DATABASE foo;
Expand Down Expand Up @@ -51,7 +53,6 @@ In a cluster:

3 row available after 100 ms, consumed after another 6 ms
----
====


[[database-management-states]]
Expand Down Expand Up @@ -91,8 +92,8 @@ However, these retries are not guaranteed to succeed, and errors may persist thr
If a database is in the `quarantined` state, retrying the last operation will not work.
====

.Retry to start a database
====
=== Retry to start a database

[source, cypher]
----
neo4j@system> START DATABASE foo;
Expand Down Expand Up @@ -146,7 +147,7 @@ neo4j@system> SHOW DATABASE foo;

1 rows available after 4 ms, consumed after another 1 ms
----
====


If repeated retries of a command have no effect, or if a database is in a `dirty` state, you may drop and recreate the database, as detailed in xref:database-administration/standard-databases/create-databases.adoc[Create database].

Expand All @@ -162,11 +163,11 @@ It produces a database dump that can be further examined and potentially repaire

When a database encounters a severe error during its normal run, which prevents it from a further operation, Neo4j stops that database and brings it into a `quarantined` state.
Meaning, it is not possible to restart it with a simple `START DATABASE` command.
You have to run `CALL dbms.unquarantineDatabase(server, database, operation)` to lift the quarantine, specifying as `server` the instance with the failing database.
You have to run `CALL dbms.unquarantineDatabase(server, database, operation)` to lift the quarantine, specifying the `server` with the failing database.

The `dbms.unquarantineDatabase()` procedure is introduced in Neo4j 2025.01 to replace the now-deprecated xref:procedures.adoc#procedure_dbms_quarantineDatabase[`dbms.quarantineDatabase`()].

After lifting the quarantine, the instance will automatically try to bring the database to the desired state.
After lifting the quarantine, Neo4j automatically tries to bring the database to the desired state.

*Syntax:*

Expand All @@ -190,13 +191,13 @@ The possible values for the optional operation are:

If you choose to clear the current cluster state, the server will try to join as a new member,
but this joining can succeed if and only if there is a majority of old members "letting" the new members in.
Let's assume your cluster has a topology with three primaries.
If there is only one server in `QUARANTINED` mode, then it is safe to choose `replaceStateKeepStore` or `replaceStateReplaceStore`.
If there are two servers in `QUARANTINED` mode, then you should not use concurrently `replaceStateKeepStore` or `replaceStateReplaceStore` for both servers because there would be no majority to let them in.
Let's assume your database has a topology with three primary allocations.
If there is only one allocation in `quarantined` mode, then it is safe to choose `replaceStateKeepStore` or `replaceStateReplaceStore`.
If there are two allocations in `quarantined` mode (meaning that the database is in the `quarantined` state on two servers), then you should not use concurrently `replaceStateKeepStore` or `replaceStateReplaceStore` for both of them because there would be no majority to let them in.

*Return arguments:*

The procedure doesn't return any value.
The procedure does not return any value.


.Check if a database is quarantined
Expand All @@ -220,9 +221,9 @@ neo4j@system> SHOW DATABASE foo;
[NOTE]
====
A `quarantined` state is persisted for user databases.
This means that if a database is quarantined, it will remain so even if that Neo4j instance is restarted.
You can remove it only by running the xref:procedures.adoc#procedure_dbms_unquarantineDatabase[`dbms.unquarantineDatabase()`] procedure.
This means that if a database is quarantined, it will remain so even if the Neo4j process is restarted.
You can remove the `quarantined` state only by running the xref:procedures.adoc#procedure_dbms_unquarantineDatabase[`dbms.unquarantineDatabase()`] procedure.

The one exception to this rule is for the built-in `system` database.
Any quarantine for that database is removed automatically after instance restart.
The one exception to this rule is for the `system` database.
Any quarantine for that database is removed automatically after the Neo4j process restart.
====
9 changes: 4 additions & 5 deletions modules/ROOT/pages/procedures.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -1173,11 +1173,10 @@ The possible values for the optional operation are:
* `replaceStateKeepStore` -- join as a new member, clearing the current cluster state but keeping the store.
* `replaceStateReplaceStore` -- join as a new member, clearing both the current cluster state and the store.

If you choose to clear the current cluster state, the server will try to join as a new member,
but this joining can succeed if and only if there is a majority of old members "letting" the new members in.
Let's assume your cluster has a topology with three primaries.
If there is only one server in `QUARANTINED` mode, then it is safe to choose `replaceStateKeepStore` or `replaceStateReplaceStore`.
If there are two servers in `QUARANTINED` mode, then you should not use concurrently `replaceStateKeepStore` or `replaceStateReplaceStore` for both servers because there would be no majority to let them in.
If you choose to clear the current cluster state, the server will try to join as a new member, but this joining can succeed if and only if there is a majority of old members "letting" the new members in.
Let's assume your database has a topology with three primary allocations.
If there is only one allocation in `quarantined` mode, then it is safe to choose `replaceStateKeepStore` or `replaceStateReplaceStore`.
If there are two allocations in `quarantined` mode (meaning that the database is in the `quarantined` state on two servers), then you should not use concurrently `replaceStateKeepStore` or `replaceStateReplaceStore` for both of them because there would be no majority to let them in.
====

[role=label--admin-only label--deprecated-5.9 label--removed-cypher-25]
Expand Down