> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/administration-guide/caddie/troubleshooting.md).

# Caddie troubleshooting

For administrators and reviewers — why a Caddie — Access Review Assistant block reads "cannot identify any user", "not enough certification history" or "not enough peer data", and what to change so it

## What this is, and when you need it

Several blocks of Caddie — Access Review Assistant answer with a sentence instead of data when they have nothing they can safely show. Each of those sentences is deliberate, but the panel does not say *why* it has nothing, and a reviewer who knows the entitlement has an owner, or that the role has been reviewed before, reasonably reads it as a fault. This page starts from the sentence on screen, explains what the block needed and did not find, and says what to change.

It is for the administrator a reviewer turns to, and for reviewers who want to know whether the message is worth reporting. If a block reads *This information could not be loaded.* with a **Retry** button, that is a different problem: the request failed, and retrying is the first step. If the Caddie button itself is missing, see [Enable Caddie](/administration-guide/caddie/enable-caddie.md).

## At a glance

| Symptom                                                                                                                              | Likely cause                                                                                           | Resolution                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
| **Ask for help** reads `Unfortunately the system cannot identify any user to ask for help from.`                                     | Every candidate helper was filtered out, most often because none of them has a published email address | [Nobody to ask for help](#nobody-to-ask-for-help)                     |
| **Ask for help** offers fewer helpers than expected                                                                                  | The same filters removed everyone behind the missing options                                           | [Nobody to ask for help](#nobody-to-ask-for-help)                     |
| **This entitlement across other users** reads `There is not enough certification history for this entitlement to show a comparison.` | Fewer than five human reviews of the entitlement exist in other campaigns, for other holders           | [Not enough certification history](#not-enough-certification-history) |
| **Peer comparison** reads `There is not enough peer data to compare this access (the peer group is too small or not configured).`    | The holder's peer cohort is too small, or could not be worked out                                      | [Not enough peer data](#not-enough-peer-data)                         |
| **Peer comparison** reads `Peer comparison is not available for this item.`                                                          | The item carries no Peer Rarity result at all                                                          | [Peer comparison not available](#peer-comparison-not-available)       |

## Nobody to ask for help <a href="#nobody-to-ask-for-help" id="nobody-to-ask-for-help"></a>

**Symptom.** The reviewer expands **Ask for help** and the block reads `Unfortunately the system cannot identify any user to ask for help from.`, although the reviewer has a manager and the entitlement has an owner. Or the block offers some options but not the one the reviewer expected, such as *Ask your manager*.

**Why.** The block looks for up to four kinds of helper for the item:

* the **entitlement owner**, the owner recorded on the role or group under review, expanded to its members when the owner is a group;
* the **application owner**, the owner of the application the access lives on;
* the reviewer's **manager**, their primary supervisor or, if none is recorded, all of their supervisors;
* the **campaign managers** of the certification.

Every person found is then checked, and dropped when any of these is true:

* **They have no published email address.** They need an email address that is both active and marked **Published** in their user profile. An address that exists but is not marked Published does not count, because nothing could be delivered to it.
* **Their status is one the deployment counts as inactive.** The list is the system property `org.openiam.ui.webconsole.inactive.user.status`, a comma-separated list of user statuses. If the property is empty, nobody is filtered on status. Only the primary status is checked.
* **They are the reviewer.** Asking yourself is not help.
* **They are the built-in system user.**

An option with nobody left is hidden. When every option is hidden, the block shows the message. The block never says which person was skipped or why, so from the reviewer's side a manager without a published address looks exactly like no manager at all.

{% hint style="warning" %}
If you do not see anyone to ask for help, make sure those users have published email addresses. Check the reviewer's manager, the entitlement owner (or the members of the owning group), the application owner and the campaign managers. Each needs an active email address marked **Published** in their user profile.
{% endhint %}

**What to do.**

1. Work out who the reviewer expected to see: their manager, the owner of the entitlement, the owner of the application, or the campaign managers.
2. Open each of those users' profiles and check their email addresses. Make sure at least one is active and marked **Published**.
3. Check the user's status against `org.openiam.ui.webconsole.inactive.user.status`. A person in one of the listed statuses is never offered, even with a published address.
4. Ask the reviewer to close the item and open it again after about a minute. The browser keeps the list of helpers for an item for about a minute, so expanding the block again straight away shows the old answer. A changed entitlement or application owner can take up to five minutes to appear, because resolved owners are reused for that long (`org.openiam.cert.caddie.help.ownerCacheSeconds`).

**One option addresses at most 25 people.** An entitlement owned by a very large group is trimmed to the first 25 members, and the reviewer is told how many were left out. The limit is the system property `org.openiam.cert.caddie.help.maxRecipients`. Only the members inside that limit are checked, so if all of them are filtered out, the option is hidden even when a later member of the group could have been written to.

{% hint style="info" %}
**For administrators: finding who was skipped.** With debug logging enabled for the certification-manager service, every expand of the block writes lines tagged `[UAR caddie help]`. A skipped person appears as `skipping <id>: no published email address` or `skipping <id>: status is <status>`, where `<id>` is the user's ID. One search for the tag follows a single panel open from the candidates found to the options offered.
{% endhint %}

## Not enough certification history <a href="#not-enough-certification-history" id="not-enough-certification-history"></a>

**Symptom.** The block **This entitlement across other users** reads `There is not enough certification history for this entitlement to show a comparison.`, even though the entitlement has been reviewed before, perhaps in this very campaign.

**Why.** The block counts only decisions that would tell you something about the entitlement rather than about the person in front of you. A review counts when all of these are true:

* a person made the decision, **certified** or **revoked**;
* it is about this same role or group;
* it was made in **another campaign**;
* it was about **another holder**, not the user being reviewed.

That leaves out:

* everything in the current campaign, including items already decided;
* the reviewed user's own past decisions, which appear in the separate [Certification history for this person](/administration-guide/caddie/certification-history.md#block-own-history) block;
* items still pending;
* items certified automatically;
* revocations made by the expiration policy.

Only the five most recent campaigns that hold a counted review are added up (`org.openiam.cert.caddie.history.maxCampaigns`, default `5`). If no campaign qualifies, or those campaigns hold fewer than five counted reviews in total (`org.openiam.cert.caddie.history.minPopulation`, default `5`), the block shows no numbers at all.

This is a privacy floor, not a gap. Over a handful of reviews, even *never revoked* would tell a reviewer how a few identifiable colleagues were decided. See [Why it is anonymised](/administration-guide/caddie/certification-history.md#history-entitlement-anonymised).

**The test is the number of reviews, not the number of campaigns.** One earlier campaign is enough when it holds at least five counted reviews. A role held by 20 people and certified by hand once gives 19 counted reviews when you look at any one of those holders, because that holder's own item is left out. A small entitlement adds up across the five most recent campaigns until it reaches five.

| Counted reviews in past campaigns                        | What the block shows                                                                   |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| None                                                     | `There is not enough certification history for this entitlement to show a comparison.` |
| 1 to 4                                                   | `There is not enough certification history for this entitlement to show a comparison.` |
| 5 or more, in one campaign or added up across up to five | A comparison: the revocation percentage, or *never revoked*                            |

**The first campaign never shows a comparison.** Decisions already made in the current campaign never count, even when they are about other users. The first campaign that covers an entitlement therefore always shows the message, however many of its items have been decided.

### Excluded by holder, not by reviewer <a href="#history-excluded-by-holder" id="history-excluded-by-holder"></a>

What is left out is the **holder**, the person whose access was reviewed. Who made the decision does not matter: the comparison never looks at the reviewer or the approver.

* Past decisions about the user under review are left out whoever made them, including you, the current reviewer. They appear in that user's [Certification history for this person](/administration-guide/caddie/certification-history.md#block-own-history) block.
* Decisions you made about other holders do count.

| Past item                                            | Counted in **This entitlement across other users**? |
| ---------------------------------------------------- | --------------------------------------------------- |
| About the user under review, decided by you          | No, it is the same holder                           |
| About the user under review, decided by someone else | No, it is the same holder                           |
| About another user, decided by you                   | Yes                                                 |
| About another user, decided by anyone else           | Yes                                                 |

For example, an entitlement held only by the user under review, and decided in two earlier campaigns, still shows the message. Both decisions are about the same holder, so neither is counted.

**Typical causes.**

* This is the first campaign that covers the entitlement.
* Only one person holds the entitlement. The block is about *other* holders, so if the reviewed user is the only person ever reviewed for this role or group, the count stays at zero however many campaigns there have been. Their own decisions appear in the [Certification history for this person](/administration-guide/caddie/certification-history.md#block-own-history) block instead.
* Earlier campaigns certified most of the entitlement's items automatically, or are still running.
* Few people hold the entitlement, so even five campaigns add up to fewer than five reviews.

**What to do.** Usually nothing: the sentence becomes a comparison once enough reviews of other holders have been decided by people in earlier campaigns. You can lower `org.openiam.cert.caddie.history.minPopulation` under [System configuration](/administration-guide/platform/system-configuration.md), but we advise against it in production. The floor is what stops the block revealing individual reviewers' decisions on a small entitlement.

### How to check <a href="#history-how-to-check" id="history-how-to-check"></a>

{% hint style="info" %}
**For administrators: the quickest check.** With debug logging enabled for the certification-manager service, every expand of the history blocks writes lines tagged `[UAR caddie history]`. When the block shows the message, the log reads `block D verdict: INSUFFICIENT_HISTORY — N campaign(s) and M review(s)`, where `N` is the number of past campaigns that hold a counted review and `M` is the number of counted reviews in them. The lines before it list each campaign that was counted.
{% endhint %}

To see why the numbers are what they are, run this query against the certification database. It lists every campaign that reviewed the entitlement, with one row per campaign, and splits its items into what Caddie counts and what it leaves out.

Replace the two placeholders before running it. Both IDs are in the reviewer's address bar when the entitlement is open: `…/uar/campaigns/<campaign id>/entitlements/<entitlement id>`. Use the campaign ID as `<current campaign id>` and the entitlement ID as `<entitlement id>`. The user ID `0001` in the query is the system user that the expiration policy revokes as.

{% code overflow="wrap" expandable="true" %}

```sql
SELECT c.ID AS campaign_id, c.NAME AS campaign_name, c.STATUS AS campaign_status, c.EXECUTION_DATE AS launched,
       CASE WHEN c.ID = '<current campaign id>' THEN 'CURRENT (excluded)' ELSE 'past' END AS which,
       COUNT(*) AS items_total,
       SUM(CASE WHEN ari.REVIEW_OUTCOME IS NULL OR ari.REVIEW_OUTCOME NOT IN ('CERTIFIED','REVOKED') THEN 1 ELSE 0 END) AS not_decided,
       SUM(CASE WHEN ari.REVIEW_OUTCOME IN ('CERTIFIED','REVOKED') AND ari.AUTO_CERTIFIED <> 'N' THEN 1 ELSE 0 END) AS auto_certified,
       SUM(CASE WHEN ari.REVIEW_OUTCOME = 'REVOKED' AND ari.ACCESS_REVOKED_BY = '0001' THEN 1 ELSE 0 END) AS revoked_by_expiry,
       SUM(CASE WHEN ari.REVIEW_OUTCOME IN ('CERTIFIED','REVOKED') AND ari.AUTO_CERTIFIED = 'N'
                 AND (ari.REVIEW_OUTCOME <> 'REVOKED' OR ari.ACCESS_REVOKED_BY IS NULL OR ari.ACCESS_REVOKED_BY <> '0001')
                THEN 1 ELSE 0 END) AS human_decisions
FROM ACCESS_REVIEW_ITEM ari JOIN CAMPAIGN c ON c.ID = ari.CAMPAIGN_ID
WHERE ari.ROLE_ID = '<entitlement id>' OR ari.GRP_ID = '<entitlement id>'
GROUP BY c.ID, c.NAME, c.STATUS, c.EXECUTION_DATE
ORDER BY c.EXECUTION_DATE DESC;
```

{% endcode %}

If your schema stores `AUTO_CERTIFIED` as `0` and `1` rather than `'N'` and `'Y'`, replace `'N'` with `0` in the query.

How to read the result:

* **Only the `CURRENT (excluded)` row comes back.** This is the first campaign that covers the entitlement, so there is nothing to compare with yet.
* **Past rows have `human_decisions` above zero, but the block still shows the message.** Either the total is below five, or the decisions are about the reviewed user themselves. `human_decisions` includes the reviewed user's own items, which Caddie then leaves out whoever decided them, so an entitlement held by one person shows decisions here and still counts zero. See [Excluded by holder, not by reviewer](#history-excluded-by-holder).
* **Past rows have `human_decisions` of zero.** The other columns say why: the items were certified automatically (`auto_certified`), are still undecided (`not_decided`), or were revoked by the expiration policy (`revoked_by_expiry`).

The block shows a comparison once past campaigns hold at least five human decisions about users other than the reviewed one.

## Not enough peer data <a href="#not-enough-peer-data" id="not-enough-peer-data"></a>

**Symptom.** The **Peer comparison** block reads `There is not enough peer data to compare this access (the peer group is too small or not configured).`

**Why.** The block reports the Peer Rarity risk factor, which compares the holder with their peer cohort: either the other people who report to the same manager, or the other members of the same organization, whichever is configured on that factor in the risk policy. The factor ran for this item but could not produce a comparison, because:

* the cohort is smaller than the factor's minimum cohort size, which defaults to 5 and cannot be set below 2;
* no cohort could be worked out, because the holder has no manager, or no organization of the configured type;
* the peer data could not be consulted when the item was scored.

**What to do.**

1. Check the holder's user profile. With a manager-based cohort, they need a manager; with an organization-based cohort, they need an organization of the configured type.
2. Check how the Peer Rarity factor's cohort and minimum cohort size are set on the risk policy; see [Risk factor reference](/administration-guide/risk/factors.md).
3. Wait for the next risk refresh, so the factor runs again with the corrected data. Open items are refreshed by a nightly risk reconciliation, which runs at 03:30 by default.

A small team is a real limit, not a fault. If a manager has three direct reports, a manager-based cohort with a minimum of 5 can never compare them.

## Peer comparison not available <a href="#peer-comparison-not-available" id="peer-comparison-not-available"></a>

**Symptom.** The **Peer comparison** block reads `Peer comparison is not available for this item.`

**Why.** The item carries no Peer Rarity reading at all, so there is nothing for the block to report. This happens when:

* the Peer Rarity factor is disabled, or not attached to the risk policy;
* the item was never scored, for example because the risk-manager service was not running when the campaign was launched;
* the item was scored before the factor existed.

**What to do.**

1. Confirm that the Peer Rarity factor is enabled and attached to the risk policy that scores certification items; see [Risk factor reference](/administration-guide/risk/factors.md).
2. Confirm that the risk-manager service is running.
3. Wait for the nightly risk reconciliation, 03:30 by default. It refreshes the scores of open items, so items that were never scored, or were scored without the factor, pick up a Peer Rarity reading.

If the message appears on every row of a campaign, the factor is not in use for that campaign. If it appears on some rows only, those items were not scored.

## Related

* [Ask for help](/administration-guide/caddie/ask-for-help.md) — who each option reaches, and what is recorded when a reviewer asks
* [Certification history](/administration-guide/caddie/certification-history.md) — what the two history blocks count
* [Peer comparison](/administration-guide/caddie/peer-comparison.md) — the cohort and the sentences the block can show
* [Enable Caddie](/administration-guide/caddie/enable-caddie.md#enable-properties) — every system property that tunes the blocks
* [Risk factor reference](/administration-guide/risk/factors.md) — where the Peer Rarity factor and its cohort are configured


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.openiam.com/administration-guide/caddie/troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.