Playbook: debug an error message or a stack trace

The question, in the user's words: "Our server logs Multiple users with email 'x' exist in Keycloak. Where does that come from, what leads to it, and who catches it?"

What you get at the end: the method that throws it, the exception type, every method that calls the thrower, and which callers catch it or turn it into an HTTP error. Every step below was run on Keycloak, a public Java project, with the release engine.

Words used on this page: an exception is an error a method throws; a caller is a method that calls another; a stack trace is the list of calls that were running when the error happened.

The steps

1. Find the line that writes the message

niro ask code_grep pattern="exist in Keycloak" path_pattern=model/ answer=locations

1 matching line in 1 file
model/jpa/src/main/java/org/keycloak/models/jpa/JpaUserProvider.java:1183  org.keycloak.models.jpa.JpaUserProvider.ensureEmailConstraint_NbykxN
[shown all 1 matching line; ask without answer= for the whole lines]

answer=locations gives the place and the exact id of the method that holds it, which the next step takes as it is. Use the fixed part of the message ("exist in Keycloak"), not the part that changes ("x").

If you have a stack trace instead, its top line already names the method and the line (at ...JpaUserProvider.ensureEmailConstraint(JpaUserProvider.java:1183)). Skip to step 2 with that name.

2. Read only that method

niro ask get_source_code fqn=org.keycloak.models.jpa.JpaUserProvider.ensureEmailConstraint

1177:     protected void ensureEmailConstraint(List<UserEntity> users, RealmModel realm) {
1178:         UserEntity user = users.get(0);
1180:         if (users.size() > 1) {
1183:             throw new ModelDuplicateException("Multiple users with email '" + user.getEmail() + "' exist in Keycloak.");
...
1196:     }

So the exception type is ModelDuplicateException, thrown when more than one user row has that email.

3. Who calls the thrower, and does anyone catch it on the way?

niro ask get_exception_flow method_fqn=org.keycloak.models.jpa.JpaUserProvider.ensureEmailConstraint direction=upstream exception_type=ModelDuplicateException

Callers of JpaUserProvider.ensureEmailConstraint reached while tracing ModelDuplicateException — 1 caller, 0 catch it.
...
  JpaUserProvider.getUserByEmail (line 704)

4. Who calls getUserByEmail?

Ask for the callers as places, not as full entries:

niro ask get_reverse_call_chain method_fqn=org.keycloak.models.UserProvider.getUserByEmail answer=locations

UserProvider.getUserByEmail has 17 callers.
confidence: complete | has_more: false — this is the COMPLETE caller chain. Use it directly.
services/src/main/java/org/keycloak/userprofile/validator/DuplicateEmailValidator.java:71  ...DuplicateEmailValidator.validate_NwtfyN
services/src/main/java/org/keycloak/partialimport/UsersPartialImport.java:82  ...UsersPartialImport.userEmailExists_NuvfpN
server-spi-private/src/main/java/org/keycloak/models/utils/KeycloakModelUtils.java:331  ...KeycloakModelUtils.findUserByNameOrEmail_Nh6f5N
... 14 more
[shown all 17 callers; ask without answer= for signatures and code]

Ask the name the callers use. The callers write session.users().getUserByEmail(...), and users() returns the UserProvider interface. In this release, asking the JPA class (JpaUserProvider.getUserByEmail) answers "0 callers", because the method is declared on a parent interface of UserProvider. This is a known problem, see FAQ: wrong or missing answers.

5. Where is it turned into an HTTP error?

For a REST method you suspect, ask what escapes it and what it catches:

niro ask get_exception_flow method_fqn=org.keycloak.services.resources.admin.UsersResource.createUser

Exceptions escaping UsersResource.createUser - 3 types, 2 swallow candidates, 6 wrapped.
...
Wrapped (caught and thrown on as a new exception of another type ...):
  ModelDuplicateException
      caught at UsersResource.createUser
...
requires_runtime: yes - treat the escaping set as "at least these", never as "exactly these".

The code at that catch is throw ErrorResponse.exists("User exists with same username or email");, which a code_grep for the message confirms at UsersResource.java:180.

Why the answer is complete, and where it is not

What grep and file reads would do instead

Step With grep What it misses or costs
1 grep -rn "exist in Keycloak" finds the line too nothing: a plain text search is the right tool here
3 to 4 grep -rn "getUserByEmail(" gives 46 lines in 35 files at least 15 of those lines are other classes' own getUserByEmail methods, not calls. grep cannot tell which getUserByEmail a call reaches, because the call site names only session.users()
5 grep -rn "catch (ModelDuplicateException" gives 34 lines in 29 files it cannot say which of them are on the path from the thrower, so each must be read

An everyday comparison: grep is like searching a phone book for everyone called "Smith". The graph is like asking the exchange who actually rang this number.

Cost

What these steps cost depends on your code and your question. How Niro counts the size of its answers, and how to measure the cost on your own tasks, is in Tokens, speed and accuracy.