From 4b0b78e97a82765c16c0077650aa1c46f0b127e5 Mon Sep 17 00:00:00 2001
From: Michael Stingl <mail@michaelstingl.com>
Date: Sun, 7 Jun 2026 23:21:33 +0200
Subject: [PATCH] docs(common-issues): explain LDAP Result Code 49 from IDM
 volume desync

Login with the built-in IDM (LibreIDM) can fail with "LDAP Result Code 49"
and HTTP 500 when the config volume (opencloud.yaml) and the data volume
(the idm bolt-store) are no longer from the same init. This happens after
reusing one volume from an earlier installation, restoring only one of the
two, or setting an internal bind password in the environment.

Add a common-issues entry that names the two idm log signatures (bind
"not found" vs "invalid credentials"), explains the config/data pair, and
gives the recovery (remove both volumes so init re-seeds a matching set).
---
 docs/admin/resources/common-issues.md | 46 +++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/docs/admin/resources/common-issues.md b/docs/admin/resources/common-issues.md
index 43a44a35..fab2bd8b 100644
--- a/docs/admin/resources/common-issues.md
+++ b/docs/admin/resources/common-issues.md
@@ -197,3 +197,49 @@ docker compose restart
 #### ⚠️ Recommendation
 
 Admins should avoid using LibreIDM in production and use OpenLDAP instead.
+
+## Login fails with LDAP Result Code 49 (Invalid Credentials)
+
+When using the built-in IDM (LibreIDM), login can fail with `Unexpected HTTP response:
+500` in the browser, and the logs show the internal directory rejecting a bind:
+
+```bash
+opencloud-1 | {"level":"error","service":"idm","bind_dn":"uid=idp,ou=sysusers,o=libregraph-idm","op":"bind","message":"not found"}
+opencloud-1 | {"level":"error","service":"idp","error":"ldap identifier backend logon connect error: LDAP Result Code 49 \"Invalid Credentials\": ","message":"identifier failed to logon with backend"}
+```
+
+The built-in IDM seeds its service-account passwords once, at first start, into a
+bolt-store on the data volume (`idm.boltdb`), matching the values `opencloud init`
+writes into `opencloud.yaml` on the config volume. The bind fails when the two volumes
+are no longer from the same `init`. The `idm` line reads either `not found` or
+`invalid credentials`; both mean the same mismatch. This usually comes from setting an
+internal LDAP password in the environment, or from reusing one volume (for example a
+restored or carried-over data volume) without the other.
+
+### Solution
+
+With the built-in IDM, do not set the internal LDAP or service passwords in `.env` or
+the environment. Let `opencloud init` generate them, and keep only
+`INITIAL_ADMIN_PASSWORD`.
+
+Treat `opencloud.yaml` (config volume) and the data volume as one set. When you back
+up, restore, or move the instance, keep them together and from the same point in time.
+
+If you do not need the existing data, remove both volumes so `init` generates a
+matching set, then start again:
+
+```bash
+docker compose down
+docker volume rm opencloud-compose_opencloud-config opencloud-compose_opencloud-data
+docker compose up -d
+```
+
+:::caution
+Deleting `idm.boltdb` alone may not be enough: it is re-seeded from the current config,
+but a bind password still set in the environment keeps the two sides out of sync.
+:::
+
+### Recommendation
+
+The built-in IDM is intended for testing and small installations. For production, use
+an external identity provider, for example Keycloak with an external LDAP.