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
- The caller lists are complete for calls the code states. "confidence: complete" means every call to that name in indexed code was placed. Calls made through reflection or built at run time are not in any list.
- The exception list is a floor, and says so. It sees
throw newand declaredthrowsin your code. It does not see what a library throws, so the answer says "requires_runtime: yes". - The graph calls in steps 3, 4 and 5 give the same answer every time on the same graph, because they are read from it, not guessed. The
code_grepcheck of the catch line in step 5 is a text search with a time limit, so on a busy machine follow itscontinue_from. A few answers can change between two builds of the same code (a known problem). - The text search in step 1 can stop early on a busy machine.
code_grephas a time limit, and then says PARTIAL with acontinue_fromto carry on. Follow it before you decide a message is not in the code.
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.
Related
- Exceptions in general, and the
get_exception_flowlimits: Debug with Niro. - Asking for short answers: Get shorter answers.
- Other debugging playbooks: a wrong value, a failing call between services, it broke after my change, config and environment, a slow path.