Troubleshoot OpenLM Router

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.

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. 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.
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.
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, 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.
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.
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, 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?. 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.
3. Reload the page. It doesn't refresh by itself.

Run one Router for each OpenLM account. See 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.
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.

Collect diagnostics

Run these commands on the Router host:

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
• Operate OpenLM Router
• OpenLM Router API reference