From 05558008187740ae1a4aced6996aad25d5a72df6 Mon Sep 17 00:00:00 2001
From: chipmonkclarity <149391454+chipmonkclarity@users.noreply.github.com>
Date: Mon, 4 Dec 2023 17:07:09 +0200
Subject: [PATCH] add troubleshooting section on concurrency with containers
 (#5678)

---
 book/run/troubleshooting.md | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/book/run/troubleshooting.md b/book/run/troubleshooting.md
index 41dcdcae3..f9a6bd25c 100644
--- a/book/run/troubleshooting.md
+++ b/book/run/troubleshooting.md
@@ -93,4 +93,21 @@ Caused by:
     make db-tools
     ./db-tools/mdbx_chk $(reth db path)/mdbx.dat | tee mdbx_chk.log
     ```
-    If `mdbx_chk` has detected any errors, please [open an issue](https://github.com/paradigmxyz/reth/issues) and post the output from the `mdbx_chk.log` file.
\ No newline at end of file
+    If `mdbx_chk` has detected any errors, please [open an issue](https://github.com/paradigmxyz/reth/issues) and post the output from the `mdbx_chk.log` file.
+
+### Concurrent database access error (using containers/Docker)
+
+If you encounter an error while accessing the database from multiple processes and you are using multiple containers or a mix of host and container(s), it is possible the error is related to `PID` namespaces. You might see one of the following error messages.
+
+```console
+mdbx:0: panic: Assertion `osal_rdt_unlock() failed: err 1' failed.
+```
+or
+
+```console
+pthread_mutex_lock.c:438: __pthread_mutex_lock_full: Assertion `e != ESRCH || !robust' failed
+```
+
+If you are using Docker, a possible solution is to run all database-accessing containers with `--pid=host` flag.
+
+For more information, check out the `Containers` section in the [libmdbx README](https://github.com/erthink/libmdbx#containers).
\ No newline at end of file