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 the reverse.
  • 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 OmniSCEF released its connection.
  • 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. This can happen after a restart, because 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. Production deployments must always terminate TLS at or before OmniSCEF.
Last updated on