Lambogenius| Symptom | Cause and fix |
|---|---|
| Production messages get AR, “Developer license accepts only test/debug messages” | The license is a developer license and the message has MSH-11 = P. Install a trial or production license, or send test traffic (T). |
| Every message gets AR, “No license installed” or an expiry message | No token is installed, or it has expired past its grace period. Install a new token from the console or LAMBOGENIUS_LICENSE. |
| A route's queue grows and nothing is delivered | The head message is blocked (on_reject = "block") or the destination is down. The route's card shows the last error. Fix the target and select Retry now, or move the message to dead letters. |
| The sender gets AE on a store-and-forward route | The queue store is unavailable: the data directory isn't writable, or the NATS cluster has lost its quorum. Check /ready and the log. |
| Startup fails with “environment variable NAME is not set” | The config uses ${NAME} and NAME is not set. Set it, or write $${ for a literal ${. |
| “store.ack_wait … must exceed route … request_timeout … by at least 5s” | Raise [store] ack_wait or lower the route's request_timeout, so a slow delivery isn't handed to another node while it is still running. |
| Callers of an HTTP source get 401 | Missing or wrong credentials for its auth. For jwt, the log says why: expired, another issuer or audience, or a signature from an unknown key. |
| Callers get 403 with “lacks role …” or “lacks scope …” | The token is valid but the calling app wasn't granted that role or scope. Assign it in the identity provider (and grant admin consent in Entra ID). |
| Every Entra ID token is refused with “another audience” | Entra v2 tokens carry the API app's application (client) ID as their audience. Set audience to that ID, not the api:// URI. |
| A destination fails with “getting an access token: … invalid_client” | The client ID or secret is wrong, or the secret expired. The route keeps retrying; fix the credentials and select Retry now. |
| Salesforce: “app_not_found” or “refresh_token scope is required” | Save the app's Policies (pre-authorized users with the integration user's profile), and add the refresh_token, offline_access scope. Changes can take a few minutes. |
| Service Bus: “Service Bus refused the token: 401” or “unauthorized” | The gateway's identity lacks the Azure Service Bus Data Sender (destination) or Data Receiver (source) role on the namespace or entity, or the shared access key is wrong. Role assignments can take a few minutes to apply. |
| Service Bus: connecting to …:5671 times out | A firewall blocks AMQP. Set transport = "websockets" to use port 443. |
| Service Bus messages are delivered twice | The lock expired while a pass-through route was still delivering, so Service Bus handed the message out again. Lower request_timeout, or raise the entity's lock duration. |
| A destination never gets some messages | Its filter doesn't match them. The console shows each destination's filter, and the route's Unmatched count; check MSH-9 by component (ADT^A08, not ADT_A01) and that the segment in a field path is in the message. |
| “route … has several destinations; add ?destination=<name>” | Admin API calls about messages need the destination for routes with several. Pause, resume and retry-now without it apply to all of them. |
| SFTP: “… has host key SHA256:…, not the configured host_key …; refusing to connect” | The server presents another host key than the one pinned. If its administrator confirms the key changed, update host_key or known_hosts; otherwise, don't connect: something may be impersonating the server. |
| SFTP: “… is not in known_hosts” | The known_hosts file has no line for that host and port. A port other than 22 is written [host]:port. hl7-edge-gateway host-key --to host:port prints the line. |
| SFTP: “the server refused the sign-in” | Wrong username, password or key, or the server doesn't have the gateway's public key. Check the server's log for the reason. |
| SFTP: a file in the folder is never read | It doesn't match pattern, it ends with the rename: suffix, or it keeps changing between listings (still being written). Moving it fails if the move: folder doesn't exist: the console shows the error. |
| Signing in says “your session ended; sign in again” | The session was idle longer than [admin.session] idle_timeout or older than max_lifetime, or someone signed it out. Sign in again. |
| “this account is locked for a while after too many failed sign-ins” | Five wrong passwords in 15 minutes lock the name for 15 minutes; the audit trail shows where they came from. Wait, or have an admin sign in another way. |
| Single sign-on comes back with “your account has no role for this gateway” | The ID token has none of the values in role_map in its roles_claim. Assign the user an app role (Entra ID: Enterprise applications, Users and groups). |
| The gateway won't start: “store encryption key … is not the key this store was used with” | A different key was configured under an ID the store already knows. Use the original key file, or give the new key a new ID and keep the old one after it. |
| The gateway won't start: “other nodes encrypt with store key …” | Another node already encrypts with a key this node doesn't have. Give every node the same keys. |
| The console warns that the store is ephemeral | The embedded store is on storage that doesn't survive a restart of the container. Use a persistent volume, or NATS JetStream. See Deployment. |
Still stuck? Run with [log] level = "info,hl7_edge_gateway=debug" and write to hello@lambogenius.com.