---
title: Troubleshoot OpenLM Router
description: Fix common OpenLM Router problems with OpenLM Platform, from a container that does not start to a failover that did not reach the clients.
product: OpenLM Platform
---

## Before you begin

Confirm these prerequisites:

- You can run `docker compose` and `curl` on the Router host.
- You know the build of each Router image that you deployed. See [Deploy OpenLM Router](https://www.openlm.com/documentation/cloud/deployment-operations/router/deployment).

Work from the symptom you can see. Most Router problems are one of three things: the container never started, the Router is not syncing with OpenLM Platform, or the clients were never moved onto the Router.

## Why does the container not start?

The following table lists symptoms, causes, and fixes for a container that does not start:

| Symptom | Cause | Fix |
| --- | --- | --- |
| The container exits at boot with `Mongo ConnectionString cannot be null or empty.` | The connection string variable is misnamed. The Router reads `MONGODB__CONNECTIONSTRING`, with two underscores. A single underscore is ignored and the value lands empty. | Correct the name in your environment file and recreate the container. The same applies to `REDIS__CONNECTIONSTRING`. |
| The container exits at boot with `Failed to convert configuration value '' at 'admissionController:routing:CorrelationMode'`. | Both `ROUTER_CORRELATION_MODE` and `ROUTER_PROXY_PROTOCOL_ENABLED` are required, and at least one of them is not set. | Add `ROUTER_CORRELATION_MODE=Ip` and `ROUTER_PROXY_PROTOCOL_ENABLED=false` to the environment of the Router, as in [Deploy OpenLM Router](https://www.openlm.com/documentation/cloud/deployment-operations/router/deployment). Keep them exactly as shown. |
| The Router logs that it cannot reach MongoDB or Redis. | The connection strings use Compose service names such as `mongo` or `redis`. The Router uses host networking, so those names do not resolve. | Publish the datastore ports on the host and use `localhost` in the connection strings, as in [Deploy OpenLM Router](https://www.openlm.com/documentation/cloud/deployment-operations/router/deployment). |
| Saving the OpenLM Platform connection fails with `Platform encryption key must be 32 bytes (256-bit) after Base64 decoding, but was 44 bytes.` | The encryption key was Base64-encoded twice. | Store the string `openssl rand -base64 32` printed, exactly as printed. It is already Base64, and encoding it again is the error. A correct key decodes to 32 bytes. |
| The Router UI container restarts repeatedly, logging `invalid number of arguments in "server_name" directive`. | The UI image requires `LB_FQDN`. | Set `LB_FQDN` on the `routerui` container, as in [Deploy OpenLM Router](https://www.openlm.com/documentation/cloud/deployment-operations/router/deployment). |
| The Router UI opens as a blank page. | Nothing strips the `/router-management` prefix, so every script request returns the page HTML instead. | Put the Router UI behind the proxy described in [Deploy OpenLM Router](https://www.openlm.com/documentation/cloud/deployment-operations/router/deployment), and open it on port `8101`. |

## Why is the Router not syncing with OpenLM Platform?

Until the Router is connected to OpenLM Platform, it has no configuration, no server list, and no health data. To find the reason, check the notice under **Platform Connection** in the Router UI, or `configurationManagement.lastSync.lastFailure` in `GET /api/v1/status`. Both report the same reason. On a new Router the reason reads:

```
No Platform connection is configured, so the Router has no address for the LicOps Configuration service
```

Both `/readyz` and `/health/ready` answer `503` while the Router has no configuration.

The notice and `lastSync` cover the configuration the Router collects from OpenLM Platform. The Router collects server health separately, so also check `GET /api/v1/platform/servers`: it must list your license servers.

The following table lists symptoms, causes, and fixes for a Router that is not syncing:

| Symptom | Cause | Fix |
| --- | --- | --- |
| `lastFailure` says no Platform connection is configured. | The OpenLM Platform connection has not been saved. | Connect the Router as described in [Configure OpenLM Router](https://www.openlm.com/documentation/cloud/deployment-operations/router/configuration). |
| `lastFailure` names an address that does not resolve or cannot be reached. | The base URL is wrong, or the host has no outbound access to OpenLM Platform. | Correct the base URL and confirm the host can reach OpenLM Platform over HTTPS. |
| The connection saves cleanly, but `GET /api/v1/platform/servers` keeps answering `503`. | The credential is valid but is not an identity client of type `Router`, so OpenLM Platform refuses the queries from the Router. The Router logs `Platform serversStatistics returned Unauthorized` and `snapshot sync skipped … (servers: AuthFailed, licenses: AuthFailed)`. | Create an identity client whose **Client Type** is `Router` in **Identity** in OpenLM Platform and enter its credentials again. A client of another type, such as an External API client, authenticates successfully and is still refused. |
| The client type is `Router` and `lastSync` shows successful syncs, but `GET /api/v1/platform/servers` keeps answering `503`. The Router logs `snapshot sync skipped … (servers: PartialFailure, licenses: PartialFailure)` with `AUTH_NOT_AUTHORIZED` for `serversStatistics` and `licenseStatistics`. | OpenLM Platform refuses this Router client the license-server data. | Contact OpenLM Support and include the log line. |
| `GET /api/v1/platform/servers` was working and starts answering `503`, health stops updating, and no failover ever fires. | No Platform sync has succeeded for 10 minutes. Either the sync is failing, or Redis was restarted empty, so the recurring jobs of the Router are gone and the sync no longer runs. | Read `lastFailure` in `GET /api/v1/status`. If it names a problem, fix that. If it is empty, restart the Router to re-register the jobs, then fix Redis persistence so it cannot recur. See [System requirements](https://www.openlm.com/documentation/cloud/deployment-operations/router/system-requirements). |
| `lastSuccessfulSync` was advancing and has stopped. | The sync is failing, usually because the OpenLM Platform connection stopped working. | Read `lastFailure`. It names the current problem and is cleared by the next success. |
| A pair's health shows `Unknown`. | The Router has had no reading for that server for 10 minutes. | The Router holds the pair where it is and does not fail over on `Unknown`. Fix OpenLM Platform sync, and the pair resumes once readings return. |

## Why does a change made in OpenLM Platform not reach the Router?

The following table lists symptoms, causes, and fixes for a change that does not reach the Router:

| Symptom | Cause | Fix |
| --- | --- | --- |
| A pair was saved in OpenLM Platform, and the Router still reports `unconfigured`. | Fewer than 10 seconds have passed, the Router is not syncing, or another Router reported to OpenLM Platform more recently, so **LicOps Configuration** showed you the pairs of that Router. | Check `lastSync` in `GET /api/v1/status`. **LicOps Configuration** works with the Router that reported most recently. If more than one Router reports to your OpenLM account, stop the ones you do not use, then reload the page. |
| A license server is missing from **Choose server**. | OpenLM Platform does not monitor it: the OpenLM Broker is not installed on the server, not approved in **Broker Hub**, or the server is not approved under **License Servers**. | Follow the Broker steps in [System requirements](https://www.openlm.com/documentation/cloud/deployment-operations/router/system-requirements#openlm-platform-prerequisites), then check that **Live Servers Statistics** shows the server as **Up**. |
| A pair saved in **LicOps Configuration** does not open its listen port, and `lastFailure` says `The Router has not collected any Platform license-server data yet`. | The Router has no server list, so it cannot resolve the pair's servers and rejects the configuration. OpenLM Platform does not show the rejection. | Get the server list working first, as described in [Why is the Router not syncing with OpenLM Platform?](#why-is-the-router-not-syncing-with-openlm-platform). The Router tries again on every sync, so the pair takes effect once the server list arrives. |
| `lastAppliedConfigVersion` stays behind, and `lastFailure` names a server. | The pair names a server that the OpenLM Platform server list on this Router does not include, so the Router refused to apply it. | Select a server that `GET /api/v1/platform/servers` lists on this Router. |
| **LicOps Configuration** says that no Router has reported itself yet. | The Router has not synced with OpenLM Platform yet, or you opened the page before it did. The page does not refresh by itself. | Confirm the OpenLM Platform connection of the Router works, then reload the page. The Router registers itself on its first successful sync. |

## Why does LicOps Configuration show the wrong Router?

**LicOps Configuration** works with the Router that reported to your OpenLM account most recently. If two Routers report, the page shows the pairs of whichever reported last, and it can switch between them from one reload to the next.

1. Compare the Router identifier on the page with `routerId` in `GET /api/v1/status` on the Router you mean to configure.
2. Stop every Router that you don't use. See [Change, upgrade, or remove OpenLM Router](https://www.openlm.com/documentation/cloud/deployment-operations/router/manage#remove-openlm-router).
3. Reload the page. It doesn't refresh by itself.

Run one Router for each OpenLM account. See [Current limitations](https://www.openlm.com/documentation/cloud/deployment-operations/router/index#current-limitations).

## Why are clients not using the Router?

The following table lists symptoms, causes, and fixes for a Router that is running while clients do not use it:

| Symptom | Cause | Fix |
| --- | --- | --- |
| A failover happened, but clients still reach the old server. | The clients point at the license server, not at the Router. | Check `LM_LICENSE_FILE` and the application's vendor-specific variable, because a vendor variable takes precedence. See [Configure OpenLM Router](https://www.openlm.com/documentation/cloud/deployment-operations/router/configuration). |
| `lmutil lmstat` through the Router works, but applications cannot check out. | The Router carries only the connection to `lmgrd`. The checkout then goes from the workstation straight to the vendor daemon on the active server, and that port is closed or changes at every restart. | Fix the vendor-daemon port in each license file with `PORT=` on the `VENDOR` line, and open it from the workstations to both servers. |
| Nothing is listening on the configured port. | The configuration was not applied, or the container uses bridge networking without that port published. | Compare the bound and wanted ports with `curl http://localhost:8100/readyz`, and prefer host networking. |
| Forcing a failover answers `409` `"Already on backup"`, but the pair is serving from its primary. | The `pairId` does not exist, or the pair has no backup. The Router answers the same way in both cases as for a pair that has already moved. | Check the name against `GET /api/v1/config`, and confirm the pair has a backup server. |
| `/api/v1/status` reports `unconfigured`. | The Router has not collected a configuration from OpenLM Platform, or no pairs are defined there. | Check the OpenLM Platform connection and `lastSync` in `GET /api/v1/status`, and confirm the pair exists in OpenLM Platform. |
| A pair that had failed over is back on its primary, and nothing requested it. | Redis lost the role key through an eviction, a flush, or a restart without persistence. | Set `maxmemory-policy noeviction` and turn on append-only persistence. See [System requirements](https://www.openlm.com/documentation/cloud/deployment-operations/router/system-requirements). |

## Collect diagnostics

Run these commands on the Router host:

```bash
docker compose logs routerapi --tail 200
curl http://localhost:8100/api/v1/status
curl http://localhost:8100/readyz
curl http://localhost:8100/api/v1/config
```

`/readyz` reports which listen ports are bound against which are wanted, which is the quickest way to tell an unapplied configuration from a networking problem.

## Related

- [Configure OpenLM Router](https://www.openlm.com/documentation/cloud/deployment-operations/router/configuration)
- [Operate OpenLM Router](https://www.openlm.com/documentation/cloud/deployment-operations/router/operations)
- [OpenLM Router API reference](https://www.openlm.com/documentation/cloud/deployment-operations/router/reference)