> 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/operations/rebuild-a-search-index.md).

# Rebuild a search index

Rebuild one OpenSearch index from the Webconsole when an object is correct on its own screen but search cannot find it.

## What this is, and when you need it

OpenIAM's search screens read OpenSearch indexes, not the database, so an object can be present and correct and still be unfindable. Rebuilding the one index that holds it is the repair — and it is the wrong move for every other symptom. Step one of the procedure is the short form of the test that separates a stale index from bad data; the full test, and the list of symptoms a reindex does and does not fix, are in [Stale index versus bad data](#stale-index-versus-bad-data-the-two-question-test) after the procedure.

## At a glance

|                          |                                                                                                                                                                                                               |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **You will end up with** | One OpenSearch index rebuilt from the database, the missing object appearing in search, and a `REINDEX` audit event that has completed rather than merely started. No identity, role or audit data is altered |
| **Where**                | `/webconsole/reindex`                                                                                                                                                                                         |
| **You need first**       | The [two-question test](#stale-index-versus-bad-data-the-two-question-test), the one index the symptom points at, and a super-administrator account — `/webconsole/reindex` accepts nobody else               |
| **Takes**                | 5 minutes to start; the rebuild reads the whole entity set, so it is slow on a large directory and competes with live search                                                                                  |
| **Reversible**           | No, and it does not need to be — a rebuild rewrites the index from the database, so re-running it is the only correction; the exception is the audit indexes, which have no database source                   |

## Before you begin

The index list — all 32, with the OpenIAM constant and the OpenSearch name — is in [Search indexes and the authorization graph](/administration-guide/reference/search-indexes.md). Open it and come back with the one entity you need.

This operation changes state, so follow [Change configuration safely](/administration-guide/start/change-safely.md), and record what you rebuilt and when: the run writes an audit event somebody will later ask you to explain.

## Rebuild the index

{% stepper %}
{% step %}

### Confirm the index is the problem

Open the object by id, from its own screen. If the value there is wrong, stop — this is a data problem, and a rebuild will re-index the wrong value faithfully.
{% endstep %}

{% step %}

### Open the reindex screen and pick one entity

Go to `/webconsole/reindex`, which lists the indexable entities. Choose the one your symptom points at — `users` or `userattributes` for a user that search cannot find, `orphan` for an orphan account, `connectorreply` for a managed system's connector replies. Rebuilding everything because you are not sure which one is the expensive way to answer that question.
{% endstep %}

{% step %}

### Start the rebuild, then leave it alone

Each run writes a `REINDEX` audit event carrying the entity it rebuilt as an audit field. Do not start a second rebuild while the first is running: each one reads the whole entity set and competes with production search.
{% endstep %}
{% endstepper %}

## Verification

Verification is not the screen accepting the request. Search for the object that was missing, and confirm the `REINDEX` audit event completed rather than merely started — the entity named on that event is how you prove afterwards that the right index was rebuilt.

## When it goes wrong

| Symptom                                                                                | Cause                                                                                                       | Where to look / fix                                                                                                                                                              |
| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Reindexed and nothing improved                                                         | The data itself is wrong                                                                                    | Open the object by id; fix the object, not the index                                                                                                                             |
| The rebuild is refused, or the screen will not open                                    | `/webconsole/reindex` requires a super-administrator                                                        | Use an account in that role, or ask someone who has it                                                                                                                           |
| Membership correct, effective access wrong                                             | This is the authorization graph, not an index                                                               | [Rebuild the authorization graph](/administration-guide/operations/rebuild-the-authorization-graph.md)                                                                           |
| Every screen backed by an index returns nothing, and no error appears on screen at all | The OpenSearch host or port is wrong; the failure is recorded in the log of whichever service ran the query | Deployment-owned — [Search indexes and the authorization graph](/administration-guide/reference/search-indexes.md), then the [Installation Guide](/installation/installation.md) |
| Audit search returns nothing for a period                                              | Either the `auditlog` index is stale, or pruning was enabled                                                | Check `org.openiam.audit.log.prune.days*` and the `PRUNE_AUDIT_LOGS` task first — [Find audit evidence](/administration-guide/operations/find-audit-evidence.md)                 |

## Rollback or cleanup

A rebuild has no undo and needs none: it rewrites the index from the database, so re-running it is the only correction there is, and the underlying objects are untouched. The exception is the audit indexes. `auditlog` and `auditlogattribute` **are** the system of record and have no database source, so a rebuild cannot restore audit documents that are gone — see [Find audit evidence](/administration-guide/operations/find-audit-evidence.md).

## Stale index versus bad data: the two-question test

Ask these in order and stop at the first "no".

1. **Open the object directly** — by id, from its own screen, not from search. Is the value right? No → the data is wrong. Fix the data; do not reindex.
2. **Does search find it?** No → the index is stale. Reindex that one index.
3. **Is the membership row right but effective access wrong?** Yes → the graph is stale. [Rebuild it](/administration-guide/operations/rebuild-the-authorization-graph.md).

Reindexing to "see if it helps" is not free: a rebuild reads the whole entity set and competes with production traffic. Rebuild one index, in a maintenance window, unless you are recovering from an outage.

### Which symptoms a reindex fixes, and which it does not

**When it is.** The object is correct in the Webconsole when you open it directly by id, but a *search* cannot find it. That asymmetry is the whole diagnostic. Specifically:

* A user exists and can log in, but does not appear in user search → `users` / `userattributes`.
* An orphan account is visible on the managed system but not on the orphan screen → `orphan`.
* Audit search returns nothing for a period you know had activity → `auditlog`, but read the caveat under [Rollback or cleanup](#rollback-or-cleanup) first.
* A managed system's connector replies are missing from the dashboard → `connectorreply`.

**When it is not.** If opening the object directly also shows the wrong value, the data is wrong and a reindex will faithfully re-index the wrong value. Check the object screen first.

## When the Webconsole itself will not start

{% hint style="warning" %}
`/webconsole/reindex` is the only reindex path you have. A Webconsole that will not start is a deployment failure, not an indexing one — fix that first, with the [Installation Guide](/installation/installation.md), and the screen comes back with it.

OpenIAM can also rebuild an index without going through the Webconsole at all, but that route is not offered to the administrator, takes no authentication and writes **no audit event**, so a rebuild run that way leaves no evidence that it happened and no record of who asked for it. If an index genuinely has to be rebuilt before the console is available, make it a support request. The same unauthenticated exposure applies to the estate-wide session operation described on [Terminate a user's sessions](/administration-guide/security/session-management.md#the-ways-a-session-ends-narrowest-first) — confirm with whoever owns your network that the ESB's port is not reachable from anywhere a user is.
{% endhint %}

## Related

* [Search indexes and the authorization graph](/administration-guide/reference/search-indexes.md) — all 32 indexes, with the OpenSearch name of each
* [Rebuild the authorization graph](/administration-guide/operations/rebuild-the-authorization-graph.md) — the other derived structure that goes stale
* [Diagnose a failed operation](/administration-guide/operations/diagnose-a-failed-operation.md) — where a stale index sits among the ten evidence layers
* [Change configuration safely](/administration-guide/start/change-safely.md) — the standard this operation assumes

*Applies to OpenIAM 2026.8.1. Last reviewed 7 August 2026.*


---

# 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/operations/rebuild-a-search-index.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.