> 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/troubleshooting/troubleshooting.md).

# Troubleshooting

Establish what is wrong, then find the page that fixes it — a triage route for an unknown fault, and an index of where every kind of problem is documented.

**Applies to:** OpenIAM 2026.10.1

## Start here when you do not know what is wrong

[**Diagnostics**](https://docs.openiam.com/installation/diagnostics.md) is the shortest path from "something is broken" to knowing what. It gives you a read-only health snapshot that takes about twenty seconds, a symptom index covering the dozen faults that account for most cases — nothing responding, a sealed secret store, a firewall, an expired certificate, a stopped connector — and a script that collects everything a support case needs.

Run the snapshot first. It tells you which tier is unhappy, and the rest of this section assumes you already know that.

{% hint style="info" %}
**Work from the bottom of the stack upwards.** The application services depend on the infrastructure tier, so one problem down there shows up as several services misbehaving at once. Confirm the infrastructure before investigating anything above it.
{% endhint %}

## When you know the symptom

Much of OpenIAM's troubleshooting lives beside the feature it belongs to rather than in this section. This is where each kind of problem is documented.

| What is wrong                                                                                                                       | Where it is covered                                                                                                                                                                                                                                                                                                                                                                                                |
| ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **An end user sees an error** — sign-in, MFA, a request, SSO                                                                        | [SelfService and login error messages](https://docs.openiam.com/troubleshooting/signing-in/selfservice-and-login-errors.md)                                                                                                                                                                                                                                                                                        |
| **One user cannot sign in**                                                                                                         | [A user cannot sign in](https://docs.openiam.com/administration-guide/security/cannot-sign-in.md)                                                                                                                                                                                                                                                                                                                  |
| **SSO or federation is broken**                                                                                                     | The matching page under [Configure federation and application SSO](https://docs.openiam.com/administration-guide/federation.md) — the SAML, OIDC and JIT pages each carry their own symptom table. To back out a federation you have just set up, or recover from being locked out by one, [Federation troubleshooting and recovery](https://docs.openiam.com/getting-started-guide/federation/troubleshooting.md) |
| **Requests never reach OpenIAM at all**                                                                                             | [Troubleshoot the gateway](https://docs.openiam.com/administration-guide/gateway/troubleshoot-the-gateway.md) — locating the failing hop between the browser and the service                                                                                                                                                                                                                                       |
| **A provisioning operation failed**, or succeeded and changed nothing                                                               | [Diagnose a failed operation](https://docs.openiam.com/administration-guide/operations/diagnose-a-failed-operation.md)                                                                                                                                                                                                                                                                                             |
| **A synchronization or reconciliation is failing** — nothing imported, a run that will not start, the same file imported every time | [Troubleshooting a synchronization run](https://docs.openiam.com/troubleshooting/connectors/synchronization-runs.md)                                                                                                                                                                                                                                                                                               |
| **You do not know which log to read**                                                                                               | [Which log answers which question](https://docs.openiam.com/administration-guide/operations/which-log-to-read.md)                                                                                                                                                                                                                                                                                                  |
| **Effective access disagrees with membership**                                                                                      | [Rebuild the authorization graph](https://docs.openiam.com/administration-guide/operations/rebuild-the-authorization-graph.md)                                                                                                                                                                                                                                                                                     |
| **An object is correct on its own screen but missing from search**                                                                  | [Rebuild a search index](https://docs.openiam.com/administration-guide/operations/rebuild-a-search-index.md)                                                                                                                                                                                                                                                                                                       |
| **Batch or scheduled tasks stopped running**                                                                                        | [Diagnose stalled batch tasks](https://docs.openiam.com/administration-guide/automation/batch-tasks/diagnose-stalled-batch-tasks.md)                                                                                                                                                                                                                                                                               |
| **A certification campaign stalled or produced nothing**                                                                            | [Diagnose a stalled campaign](https://docs.openiam.com/administration-guide/governance/certification/diagnose-a-stalled-campaign.md)                                                                                                                                                                                                                                                                               |
| **SoD detection is not reporting violations**                                                                                       | [SoD detection and violations](https://docs.openiam.com/administration-guide/governance/sod/sod-detection-and-violations.md)                                                                                                                                                                                                                                                                                       |
| **Audit events are missing, or timestamps look wrong**                                                                              | [Find audit evidence](https://docs.openiam.com/administration-guide/operations/find-audit-evidence.md), [Timestamps off by a fixed offset](https://docs.openiam.com/administration-guide/operations/timestamps-off-by-a-fixed-offset.md)                                                                                                                                                                           |
| **One connector is misbehaving**                                                                                                    | That connector's own page in [Connector configuration](https://docs.openiam.com/connector-configuration/connectorconfig.md), then [General connector troubleshooting](https://docs.openiam.com/connector-configuration/4-troubleshootingconnector.md)                                                                                                                                                              |
| **The installation itself failed**                                                                                                  | [RPM single node](https://docs.openiam.com/installation/rpm/rpm-single-node/troubleshoot.md), [RPM HA](https://docs.openiam.com/installation/rpm/rpm-ha/troubleshoot.md), [Kubernetes](https://docs.openiam.com/installation/kubernetes/troubleshoot.md)                                                                                                                                                           |
| **You need a deployment back in a clean state**                                                                                     | [Starting again cleanly](https://docs.openiam.com/installation/rpm/rpm-single-node/troubleshoot.md#starting-again-cleanly) — the uninstall script, then reinstall and re-initialize                                                                                                                                                                                                                                |

## The areas covered here

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Getting help &#x26; escalating</strong></td><td>When to self-resolve vs. escalate, and what to collect before opening a ticket.</td><td><a href="https://docs.openiam.com/troubleshooting/getting-help.md">Getting help and escalating</a></td></tr><tr><td><strong>Signing in and access</strong></td><td>Nobody can sign in, one person cannot, or someone is in but cannot see what they should.</td><td><a href="https://docs.openiam.com/troubleshooting/signing-in.md">Signing in and access</a></td></tr><tr><td><strong>The message broker</strong></td><td>RabbitMQ — a cluster that will not form, and a queue the consumer cannot get past.</td><td><a href="https://docs.openiam.com/troubleshooting/message-broker.md">The message broker</a></td></tr><tr><td><strong>Databases</strong></td><td>Migrations that will not validate, write conflicts under load, a corrupted encryption block.</td><td><a href="https://docs.openiam.com/troubleshooting/databases.md">Databases</a></td></tr><tr><td><strong>Memory, storage and performance</strong></td><td>The host running out of something, or a service not allowed enough of it.</td><td><a href="https://docs.openiam.com/troubleshooting/performance.md">Memory, storage and performance</a></td></tr><tr><td><strong>Logs and diagnostics</strong></td><td>Turning up the detail, and what goes wrong with audit documents and reports.</td><td><a href="https://docs.openiam.com/troubleshooting/logs-and-diagnostics.md">Logs and diagnostics</a></td></tr><tr><td><strong>Interface customization</strong></td><td>Labels, menu items and the properties behind them.</td><td><a href="https://docs.openiam.com/troubleshooting/interface.md">Interface customization</a></td></tr><tr><td><strong>Synchronization and connectors</strong></td><td>A run that will not start or imports the wrong thing, and where the per-connector pages are.</td><td><a href="https://docs.openiam.com/troubleshooting/connectors.md">Synchronization and connectors</a></td></tr><tr><td><strong>Deployment routes</strong></td><td>Package dependencies on RPM, and working through a Kubernetes cluster.</td><td><a href="https://docs.openiam.com/troubleshooting/deployment.md">Deployment routes</a></td></tr></tbody></table>


---

# 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/troubleshooting/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.
