docs: update keycloak realm export documentation with hint to possibl…

…e error
sovity · Dec 20, 2024 · 15f4dc7 · 15f4dc7
1 parent 80ebabe
commit 15f4dc7
Showing 1 changed file with 9 additions and 0 deletions.
diff --git a/authority-portal-backend/docs/dev/keycloak-realm-export/README.md b/authority-portal-backend/docs/dev/keycloak-realm-export/README.md
@@ -13,6 +13,15 @@ To run this script, execute the following command from the backend project's roo
 ./docs/dev/keycloak-realm-export/extract-realm.sh
 ```
 
+After the script has run, the exported [realm.json](../../../authority-portal-quarkus/src/main/resources/realm.json) may contain unrecognized fields which leads to an import error on next startup.
+Quarkus indicates those with an error message on startup like this:
+
+```
+2024-12-20 10:08:44,484 ERROR [io.qua.oid.dep.dev.key.KeycloakDevServicesProcessor] (build-57) Realm realm.dev.json resource can not be opened: Unrecognized field "firstBrokerLoginFlow" (class org.keycloak.representations.idm.RealmRepresentation), not marked as ignorable [...]
+```
+
+To fix this, remove the unrecognized fields from the exported [realm.json](../../../authority-portal-quarkus/src/main/resources/realm.json) file.
+
 ### Why do we need this script?
 
 Manually keeping track of the Realm Config JSON is very tedious. Editing the realm through Keycloak remains the easiest way