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

# Troubleshooting guide for RPM

Collecting the right logs from an RPM deployment — for a failed installation, for one service, and for a problem you can reproduce on demand.

| Symptom                                 | Likely cause                | Resolution                                                   |
| --------------------------------------- | --------------------------- | ------------------------------------------------------------ |
| The installation failed                 | Whatever `init.log` records | [Installation logs](#the-installation-log)                   |
| One service is misbehaving              | That service's own log      | [Service logs](#one-services-log)                            |
| A screen fails and you can reproduce it | The ESB first, the UI last  | [Capture just the failure](#capture-only-the-failing-action) |

## Read the logs in this order

The interface depends on the ESB, so its log reports consequences rather than causes. Reading it first sends you after symptoms of a problem that is recorded plainly somewhere else.

{% stepper %}
{% step %}
**The ESB log first.** `openiam-esb.log` is where a sign-in refusal, a content-provider mismatch or a failed rule evaluation is recorded.
{% endstep %}

{% step %}
**Then the service that owns the operation** — IDM, workflow, authentication, synchronization, reconciliation, email, and the rest.
{% endstep %}

{% step %}
**The UI log last**, and only if the first two had nothing.
{% endstep %}
{% endstepper %}

[Which log answers which question](/administration-guide/operations/which-log-to-read.md) maps symptoms to services, which is quicker than reading in order when you already know what failed.

## The installation log

A failed installation writes `init.log` into the OpenIAM home directory:

```bash
ls -lrth /usr/local/openiam | grep init
```

```
-rw-r--r--.  1 root    root    222K Jan 29 13:54 init.log
```

## One service's log

Every service writes to `/usr/local/openiam/logs`:

```bash
ls -lrth /usr/local/openiam/logs
```

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

```
-rw-r--r--. 1 openiam openiam  41K Feb  2 10:19 business-rule-manager.log
-rw-r--r--. 1 openiam openiam  41K Feb  2 10:19 reconciliation.log
-rw-r--r--. 1 openiam openiam  41K Feb  2 10:19 synchronization.log
-rw-r--r--. 1 openiam openiam  41K Feb  2 10:19 groovy-manager.log
-rw-r--r--. 1 openiam openiam  53K Feb  2 10:19 workflow.log
-rw-r--r--. 1 openiam openiam  43K Feb  2 10:19 device-manager.log
-rw-r--r--. 1 openiam openiam  86K Feb  2 10:21 idm.log
-rw-r--r--. 1 openiam openiam  61K Feb  2 10:21 email-manager.log
-rw-r--r--. 1 openiam openiam  61K Feb  2 10:21 auth-manager.log
-rw-r--r--. 1 openiam openiam 168K Feb  2 10:51 openiam-esb.log
```

{% endcode %}

The interface is separate — it writes Tomcat's logs to `/usr/local/openiam/ui/logs`, where `catalina.out` is the current one:

```bash
ls -lrth /usr/local/openiam/ui/logs | grep catalina
```

{% code overflow="wrap" %}

```
-rw-r-----. 1 openiam openiam 927K Jan 29 18:50 catalina.2025-01-29.log
-rw-r-----. 1 openiam openiam 1.8M Feb  2 10:23 catalina.out
-rw-r-----. 1 openiam openiam 272K Feb  2 10:23 catalina.2025-02-02.log
```

{% endcode %}

## Two ways to read a service, and they take different names

{% hint style="danger" %}
**`openiam-cli log` takes the log name; `journalctl -u` takes the systemd unit. They are mostly not the same string.** Passing a log name to `journalctl` returns no output at all — which reads like a service that logged nothing, rather than like a name that does not exist.
{% endhint %}

| Service                | `openiam-cli log <name>` | `journalctl -u <unit>`    |
| ---------------------- | ------------------------ | ------------------------- |
| Enterprise service bus | `openiam-esb`            | `openiam-esb`             |
| Identity management    | `idm`                    | `openiam-idm`             |
| Authentication         | `auth-manager`           | `openiam-auth`            |
| Workflow               | `workflow`               | `openiam-workflow`        |
| Synchronization        | `synchronization`        | `openiam-synchronization` |
| Reconciliation         | `reconciliation`         | `openiam-reconciliation`  |
| Email                  | `email-manager`          | `openiam-email`           |
| Groovy                 | `groovy-manager`         | `openiam-groovy`          |
| Device                 | `device-manager`         | `openiam-device`          |
| Business rules         | `business-rule-manager`  | `openiam-business-rule`   |
| Audit                  | `audit-log-manager`      | `openiam-auditlog`        |
| Batch tasks            | `batch-task-manager`     | `openiam-batchtask`       |

[Commands](/installation/commands.md) carries the full mapping, including the services not listed above.

## Capture only the failing action

Sending a whole application log means sending a lot of unrelated history. When the problem can be reproduced on demand, capture just the part that covers it.

{% stepper %}
{% step %}
**Start capturing**, naming the log of the service you expect to fail:

{% code overflow="wrap" %}

```bash
tail -f /usr/local/openiam/logs/openiam-esb.log > /tmp/esb_live_issue.txt
```

{% endcode %}

`tail -f` follows the end of the live log and writes everything that arrives into the new file.
{% endstep %}

{% step %}
**Reproduce the problem** in the application while that is still running.
{% endstep %}

{% step %}
**Stop the capture** with **Ctrl + C** once the error has happened.
{% endstep %}

{% step %}
**Send `/tmp/esb_live_issue.txt`** with the support ticket. It holds only what was written during the failing action — see [Getting help and escalating](/troubleshooting/getting-help.md) for what else to include.
{% endstep %}
{% endstepper %}


---

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