> 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/installation/rpm/rpm-single-node/troubleshoot.md). # Troubleshoot Symptom, meaning and action for the issues that come up during and after a single-node installation. Find your symptom, confirm the meaning, take the action. Everything here is safe to run on a live deployment unless the entry says otherwise. ## Set these first Two names appear throughout this page. **They are not always the same** — the unit-to-log-name mapping is in [*Commands*](/installation/commands.md#logs). {% code overflow="wrap" %} ```bash export UNIT= export SERVICE= ``` {% endcode %} ## First, orient yourself Three commands tell you where you are: {% code overflow="wrap" %} ```bash pgrep -c -u openiam java # how many services are running tail -30 /usr/local/openiam/logs/$SERVICE.log # what a specific service is saying systemctl status "openiam-$UNIT" # what the host thinks of it ``` {% endcode %} **Work from the bottom of the stack upwards.** The application services depend on the infrastructure tier, so a problem there shows up as several services misbehaving at once. Confirm the infrastructure first and most symptoms explain themselves. *** ## During installation | What you see | What it means | What to do | | ------------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | A message that free disk or available RAM is short | The host is below the requirement for the environment you selected | Provision to [*What you need*](/installation/what-you-need.md) and run again | | `Disable the swap and run openiam-cli init again` | A swap device is active | `swapoff -a`, remove the `/etc/fstab` entry, run again | | `OpenIAM is already initialized` | The host has been initialised before | Reinstall the package for a clean host, then run the initialisation | | A prompt to download a component manually | A component was not retrieved | Stop, place the named file at the path given, and start the installation again | | Package errors during an air-gapped run | The dependency repository does not match the host's Enterprise Linux version | Confirm it matches `PLATFORM_ID`, replace it, and restart the procedure | | Package repositories set aside after an interrupted run | The run did not reach the step that restores them | `cd /etc/yum.repos.d/ && for f in *.disabled; do mv "$f" "${f%.disabled}"; done` | | The initialisation appears to pause for a long time | Normal — the database migration and tier configuration take time | Allow the full 45–75 minutes. `tail -f /usr/local/openiam/init.log` shows progress | *** ## Services ### Fewer services running than expected **Check the infrastructure tier first.** The application services wait for it before they start. {% code overflow="wrap" %} ```bash curl -sk https://localhost:8200/v1/sys/seal-status | jq '.sealed' # expect false nodetool status # expect one node UN redis-cli -a "$REDIS_PASSWORD" PING # expect PONG rabbitmqctl status | head -5 # expect a running broker ``` {% endcode %} Bring up whatever is not answering, then: {% code overflow="wrap" %} ```bash openiam-cli start ``` {% endcode %} and re-run the checks in [*Start and verify*](/installation/rpm/rpm-single-node/start-and-verify.md). ### A single service is not running {% code overflow="wrap" %} ```bash systemctl restart "openiam-$UNIT" sleep 60 pgrep -af "openiam-$SERVICE" openiam-cli log "$SERVICE" # or: tail -50 "/usr/local/openiam/logs/$SERVICE.log" ``` {% endcode %} The log names the cause. The common ones: | In the log | Meaning | Action | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | SELinux denials | A policy is blocking a component | Confirm `getsebool httpd_can_network_connect` is `on`. If the search tier times out during installation on a strictly hardened host, set SELinux to permissive for the installation and re-enable it afterwards | | Database connection failures | The database is unreachable or the credentials are wrong | Confirm the database is running and reachable from this host | | Broker connection failures | The message broker is not ready | `systemctl status rabbitmq-server`, start it, restart the service | | Secret store errors | The secret store is sealed or unreachable | Confirm the seal status; unseal if required | | `OutOfMemoryError` | The service needs more heap than it has for your data volume. No service sets `-Xmx`, so its heap comes from the container's memory limit | Raise that service's `memory` limit in `conf/starter/services/` and redeploy — see [Service memory](/installation/tuning.md#service-memory) for the shipped defaults. If it recurs at a sensible limit, that is a sizing question for OpenIAM support | ### A service starts and then stops again Usually a dependency that is present but not yet ready. Start the infrastructure tier, wait for it to settle, then start the platform: {% code overflow="wrap" %} ```bash openiam-cli stop # confirm the infrastructure tier is healthy openiam-cli start ``` {% endcode %} *** ## Console and access | What you see | What it means | What to do | | ------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | | Console reachable on the host, not from elsewhere | The host firewall does not allow the reverse proxy's ports | `firewall-cmd --permanent --add-port=80/tcp --add-port=443/tcp && firewall-cmd --reload` | | A gateway or proxy error in the browser | The front-end service behind that path is not running | Check the health endpoints in [*Start and verify*](/installation/rpm/rpm-single-node/start-and-verify.md) and restart the service concerned | | Sign-in page loads, credentials rejected | The account, its password, or its status | Confirm the account is active in the console; for the initial administrator, check the installation record | | Links in email point at `localhost` | The content provider's domain pattern is not the published address | Edit it in the console — [*First sign-in*](/installation/rpm/rpm-single-node/first-sign-in.md) step 3 | *** ## Infrastructure tier ### Search tier reports `yellow` Expected on a single node — replica shards have nowhere to go. No action. ### Graph storage is not answering {% code overflow="wrap" %} ```bash systemctl status cassandra nodetool status ``` {% endcode %} If the node is down, start it and allow a minute before starting the platform. Graph storage is the tier most sensitive to being started after the services that use it, so bring it up first. ### Stop the platform before restarting the host The secret store seals when it is stopped without a clean shutdown, and the platform's services cannot read their credentials from a sealed store. `openiam-cli stop` shuts it down cleanly, so it comes back unsealed without intervention: {% code overflow="wrap" %} ```bash openiam-cli stop ``` {% endcode %} If a host has already been restarted without it: {% code overflow="wrap" %} ```bash curl -sk https://localhost:8200/v1/sys/seal-status | jq ``` {% endcode %} Unseal it with the keys recorded at installation, then `openiam-cli start`. Make `openiam-cli stop` part of your host maintenance routine — before patching, before a planned restart, before a hypervisor operation. ### The secret store is sealed {% code overflow="wrap" %} ```bash curl -sk https://localhost:8200/v1/sys/seal-status | jq ``` {% endcode %} If `sealed` is `true`, unseal it with the keys recorded at installation, then start the platform. Services cannot read their credentials while it is sealed. *** ## Logs
WhatWhere
Installation/usr/local/openiam/init.log
A service/usr/local/openiam/logs/<name>.log, or openiam-cli log "$SERVICE". The mapping from unit to log name is in Commands
A connectoropeniam-cli connector <name> log
Reverse proxy/var/log/httpd/mod_openiam_error_log and mod_openiam_access_log
Interface router/var/log/nginx/
Host servicesjournalctl -u "openiam-$UNIT"
**Treat the installation log as sensitive.** It records the configuration of the deployment; store it accordingly and remove it from the host once you have kept a copy somewhere appropriate. *** ## Starting again cleanly If an initialisation did not complete and the deployment needs rebuilding rather than repairing, remove it completely before running `openiam-cli init` again — a second run on a partially initialised host is not supported. {% code overflow="wrap" %} ```bash openiam-cli stop /usr/local/openiam/utils/uninstall.sh ``` {% endcode %} This removes the platform, its bundled components, the service accounts and the data. Confirm the marker is gone before reinstalling: {% code overflow="wrap" %} ```bash ls /usr/local/openiam/initialized # expect: No such file or directory ``` {% endcode %} Then reinstall the package and run the initialisation from [*Install*](/installation/rpm/rpm-single-node/install.md). A fresh host is the fastest route where one is available, and it is the one to use if the run failed before the secret store was configured. Removing only the package (`rpm -e openiam`) leaves configuration directories, the service account and the host settings in place, which is why the uninstall script above is the route to a clean host. ## Contacting support [*Diagnostics*](/installation/diagnostics.md) has a collection script that gathers everything below in one archive, and the four things worth including in the case. In short: * The OpenIAM version — `rpm -q openiam` * The operating system — `grep PLATFORM_ID /etc/os-release` * Which shape you built, and whether the database is local or remote * The output of the checks in [*Start and verify*](/installation/rpm/rpm-single-node/start-and-verify.md) * The log for the service concerned **Review anything you send.** Service logs can contain identity data from your environment, and the installation log records the deployment's configuration. ## Related * [*Start and verify*](/installation/rpm/rpm-single-node/start-and-verify.md) * [*Configure*](/installation/rpm/rpm-single-node/configure.md) * [*Ports*](/installation/rpm/rpm-single-node/ports.md) * [*Commands*](/installation/commands.md) *Applies to OpenIAM 2026.8.1.* --- # 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/installation/rpm/rpm-single-node/troubleshoot.md?ask=&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.