# 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](https://help.niroai.dev/cli/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 new` and declared `throws` in 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_grep` check of the catch line in step 5 is a text search with a time limit, so on a busy machine follow its `continue_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_grep` has a time limit, and then says PARTIAL with a `continue_from` to 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](https://help.niroai.dev/cli/tokens-speed-and-accuracy/).

## Related

- Exceptions in general, and the `get_exception_flow` limits: [Debug with Niro](https://help.niroai.dev/cli/lifecycle-debug/).

- Asking for short answers: [Get shorter answers](https://help.niroai.dev/cli/answer-shapes/).

- Other debugging playbooks: [a wrong value](https://help.niroai.dev/cli/playbook-debug-wrong-value/), [a failing call between services](https://help.niroai.dev/cli/playbook-debug-failing-service-call/), [it broke after my change](https://help.niroai.dev/cli/playbook-debug-after-a-change/), [config and environment](https://help.niroai.dev/cli/playbook-debug-config/), [a slow path](https://help.niroai.dev/cli/playbook-debug-slow-path/).