From c0fba3578d0d4afa59052ff4512c7cacbf2b6763 Mon Sep 17 00:00:00 2001
From: Alexey Shekhirin <a.shekhirin@gmail.com>
Date: Tue, 20 Jun 2023 16:54:06 +0100
Subject: [PATCH] chore(book): troubleshooting db issues (#3271)

---
 book/SUMMARY.md             |  1 +
 book/run/run-a-node.md      |  1 +
 book/run/troubleshooting.md | 38 +++++++++++++++++++++++++++++++++++++
 3 files changed, 40 insertions(+)
 create mode 100644 book/run/troubleshooting.md

diff --git a/book/SUMMARY.md b/book/SUMMARY.md
index 9bcc6d8d2..8faf1b1ab 100644
--- a/book/SUMMARY.md
+++ b/book/SUMMARY.md
@@ -10,6 +10,7 @@
    1. [Mainnet or official testnets](./run/mainnet.md)
    1. [Metrics](./run/observability.md)
    1. [Configuring Reth](./run/config.md)
+   1. [Troubleshooting](./run/troubleshooting.md)
 1. [Interacting with Reth over JSON-RPC](./jsonrpc/intro.md)
    1. [eth](./jsonrpc/eth.md)
    1. [web3](./jsonrpc/web3.md)
diff --git a/book/run/run-a-node.md b/book/run/run-a-node.md
index 1363761b9..164d76945 100644
--- a/book/run/run-a-node.md
+++ b/book/run/run-a-node.md
@@ -6,5 +6,6 @@ In this chapter we'll go through a few different topics you'll encounter when ru
 1. [Running on mainnet or official testnets](./mainnet.md)
 1. [Logs and Observability](./observability.md)
 1. [Configuring reth.toml](./config.md)
+1. [Troubleshooting](./troubleshooting.md)
 
 In the future, we also intend to support the [OP Stack](https://stack.optimism.io/docs/understand/explainer/), which will allow you to run Reth as a Layer 2 client. More there soon!
\ No newline at end of file
diff --git a/book/run/troubleshooting.md b/book/run/troubleshooting.md
new file mode 100644
index 000000000..4fb2ef61e
--- /dev/null
+++ b/book/run/troubleshooting.md
@@ -0,0 +1,38 @@
+# Troubleshooting
+
+As Reth is still in alpha, while running the node you can experience some problems related to different parts of the system: pipeline sync, blockchain tree, p2p, database, etc.
+
+This page tries to answer how to deal with the most popular issues.
+
+## Database
+
+### Database write error
+
+If you encounter an irrecoverable database-related errors, in most of the cases it's related to the RAM/NVMe/SSD you use. For example:
+```console
+Error: A stage encountered an irrecoverable error.
+
+Caused by:
+   0: An internal database error occurred: Database write error code: -30796
+   1: Database write error code: -30796
+```
+
+or
+
+```console
+Error: A stage encountered an irrecoverable error.
+
+Caused by:
+   0: An internal database error occurred: Database read error code: -30797
+   1: Database read error code: -30797
+```
+
+1. Check your memory health: use [memtest86+](https://www.memtest.org/) or [memtester](https://linux.die.net/man/8/memtester). If your memory is faulty, it's better to resync the node on different hardware.
+2. Check database integrity:
+    ```bash
+    git clone https://github.com/paradigmxyz/reth
+    cd reth
+    make db-tools
+    db-tools/mdbx_chk $(reth db path)/mdbx.dat
+    ```
+    If `mdbx_chk` has detected any errors, please [open an issue](https://github.com/paradigmxyz/reth/issues) and post the output.
\ No newline at end of file