Skip to main content

OmniSCEF Troubleshooting

Problem/resolution guidance for common OmniSCEF operational issues. For the underlying flows, see NIDD and Monitoring Events; for parameters, see the Configuration Reference.

Table of Contents​

MME Cannot Connect Over T6a​

Symptoms: The MME cannot establish a Diameter connection to OmniSCEF; no capabilities exchange completes.

Possible causes:

  • Firewall blocking the Diameter port (default 3868).
  • Transport mismatch — the MME uses SCTP while only TCP is reachable, or vice versa.
  • Peer authorisation is restricted and the MME is not a configured peer.
  • Origin-Host / realm mismatch between what the MME expects and what OmniSCEF advertises.

Resolution:

  1. Confirm the firewall allows the configured listen_port on both TCP and SCTP — OmniSCEF listens on both. See Listeners.
  2. Verify the MME's configured transport matches. Both TCP and SCTP listeners are always started.
  3. If allow_undefined_peers_to_connect is false, add the MME to peers with its exact Origin-Host. See Peers.
  4. Confirm OmniSCEF's host and realm match what the MME is provisioned to talk to. Check the log_unauthorized_peer_connection_attempts log output for rejected attempts.

Connection Rejected With USER_UNKNOWN (5001)​

Symptoms: The MME establishes the Diameter connection, but a NIDD connection request (CMR) is answered with DIAMETER_ERROR_USER_UNKNOWN (5001).

Possible causes:

  • No NIDD configuration exists for that subscriber's IMSI.
  • The Application Server created a configuration using an external identity that does not resolve to the subscriber's IMSI.

Resolution:

  1. Confirm the Application Server has created a NIDD configuration for the device before the UE attaches.
  2. Verify the device's externalId/msisdn resolves to the correct IMSI in the identity map.
  3. Confirm the IMSI in the identity map matches the IMSI the MME presents in the CMR.

Symptoms: A POST to downlink-data-deliveries returns a delivery whose deliveryStatus is a FAILURE_* value, or a 404.

Possible causes:

  • No active T6a connection exists for the device (404 NIDD_CONFIGURATION_NOT_AVAILABLE) — the UE has not attached, or its connection was released.
  • The UE is unreachable (FAILURE_UE_NOT_REACHABLE).
  • The MME / serving node rejected the request (FAILURE_REMOTE_FAILURE).
  • The data field is missing or not valid base64 (400 DATA_MISSING).

Resolution:

  1. Confirm the device is attached and its connection is established (a prior CMR was accepted).
  2. Check the data field is present and base64-encoded.
  3. For an idle UE, expect the MME to buffer and page; the delivery reports success once the MME takes responsibility. See Mobile-Terminated Data.
  4. For FAILURE_REMOTE_FAILURE, inspect the MME/serving-node side for the rejection cause.

Symptoms: The UE sends uplink data, but the Application Server's callback is not invoked.

Possible causes:

  • The device has no NIDD configuration (so no callback is known).
  • The notificationDestination URL is unreachable from OmniSCEF, or returns a non-2xx status.
  • No active binding exists for the {IMSI, EBI} presented on the uplink.

Resolution:

  1. Confirm a NIDD configuration exists for the device and carries a reachable notificationDestination.
  2. Verify network connectivity from OmniSCEF to the callback URL, including TLS trust if it is HTTPS.
  3. Confirm the callback returns a 2xx status; a non-2xx is treated as a delivery failure.
  4. Confirm the device attached (a CMR was accepted) before sending uplink data.

Symptoms: A downlink to a group configuration returns 404 NIDD_CONFIGURATION_NOT_AVAILABLE, or reaches fewer devices than expected.

Possible causes:

  • The externalGroupId is not present in the group map, or maps to no members.
  • No group member currently has an active T6a connection.

Resolution:

  1. Confirm the externalGroupId is defined in the group map and lists the expected member IMSIs.
  2. Confirm at least one member device is attached — only members with an active connection receive the delivery. The aggregate status reflects the worst per-member outcome. See Group NIDD.

Monitoring Reports Not Delivered​

Symptoms: A monitoring subscription is created, but the Application Server receives no notifications.

Possible causes:

  • The event was never armed in the network (no monitoring destination configured, and no other path armed it).
  • The report's SCEF-Reference-ID does not match a live subscription (for example, after a restart — subscription state is in-memory).
  • The subscription's notificationDestination is unreachable.

Resolution:

  1. If OmniSCEF should arm the event, configure a monitoring destination so the CIR is sent.
  2. Recreate subscriptions after an OmniSCEF restart — subscription and reference-ID state is volatile and does not survive a restart.
  3. Verify connectivity from OmniSCEF to the subscription callback.

T8 API Returns 404 for a Valid Endpoint​

Symptoms: A request to a documented T8 path returns 404, and the endpoint does not appear in the OpenAPI document at /api/schema.

Possible causes:

  • The route table was changed but the API layer was not recompiled, so the new route is not registered.
  • The request omits the /api prefix that all T8 routes are mounted under.

Resolution:

  1. Confirm the request path includes the /api prefix (e.g. /api/3gpp-nidd/v1/{scsAsId}/configurations).
  2. If the route table was modified, the API dependency must be recompiled so the new routes register (mix deps.compile api_ex --force), then the service restarted.

T8 Endpoint Will Not Start​

Symptoms: OmniSCEF fails to start the T8 HTTPS endpoint.

Possible causes:

  • The TLS certificate or key file is missing or unreadable.
  • The configured port is already in use.

Resolution:

  1. Confirm tls_cert_path and tls_key_path point to valid, readable PEM files. See T8 API Endpoint.
  2. Confirm nothing else is bound to the configured port on the listen_ip interface.
  3. To run without TLS in a controlled environment, set enable_tls: false — but production deployments should always terminate TLS at or before OmniSCEF.
Last updated on