> For the complete documentation index, see [llms.txt](https://docs.gxc.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gxc.io/docs/troubleshooting/onyx-troubleshooting-guide/operations-and-administration-issues.md).
# Operations & Administration Issues
This chapter covers Onyx Portal administration, configuration, subscriber and SIM/eSIM management, and monitoring issues that are typically observed by users.
For Onyx Portal navigation and status indicator definitions, see [*Onyx Portal Navigation & Indicators Reference*](/docs/troubleshooting/onyx-troubleshooting-guide/onyx-portal-navigation-and-indicators-reference.md).
## Access & Account Management
This section covers issues with Onyx Portal login, authentication, and account activation.
Unable to Log in to Onyx Portal
**Symptoms**
A user is unable to log in to the Onyx Portal.
**Indicators**
* The Onyx Portal login page displays the message "*User login was not successful or could not meet the requirements of the requesting application.*"
* A redirect loop occurs between the Onyx Portal login page and the Customer IdP login page after completing SSO authentication.
* A blank screen appears after entering login credentials.
* The MFA OTP is rejected as invalid.
**Possible Causes**
* User account status is Suspended, Verification Pending, or Password Expired — preventing login until the status is resolved.
* The authenticator device is out of synchronization, resulting in invalid OTPs.
* An SSO/IdP integration issue prevents SAML-based authentication.
* SAML certificate between Onyx Portal and the Customer IdP has expired.
* JWT token has expired (API access users).
* The browser is blocking third-party cookies required for the SAML SSO authentication flow.
* Onyx Portal service is unavailable.
**Actions**
1. Determine scope of the issue:
* If all users are affected, focus on Onyx Portal service health or IdP connectivity.
* If only one user is affected, focus on the user's account status and MFA configuration.
2. Verify user account status — In the **Administration** > **Users** tab, verify the account status is one of the following:
* **Verified** — The account is active.
* **Verification Pending** — An administrator can resend the activation link.
* **Password Expired** — The user can reset their own password using the **Reset/Forgot Password** option on the login screen.
* **Suspended** — An administrator can reactivate the account.
3. Verify MFA token synchronization:
* Verify that the authenticator device is configured to synchronize its date, time, and time zone automatically. The OTP refreshes every 30 seconds and remains valid for one minute. If login fails due to an invalid OTP, enable automatic date, time, and time zone synchronization on the authenticator device.
* If OTP validation continues to fail:
* If the user has MFA backup codes (provided when MFA was first enabled), instruct the user to sign in using a backup code instead of the OTP.
* If backup codes are unavailable, an administrator can reset the user's MFA secret via the **Administration** > **Users** tab.
4. Verify Customer IdP integration (SSO deployments) — Verify that:
* The external IdP is accessible.
* The SAML federation metadata is current.
Refer to the *4G & 5G Onyx Portal Integration with Customer IdP Application Note*.
5. Verify SAML certificate expiry — In **Administration**, click **Edit SSO Config**. In the **Edit SSO Config** dialog box, verify the **Additional Config** > **IdP Certificate** has not expired. An expired certificate prevents all SSO users from logging in.
6. Verify JWT token validity (API access users) — If the JWT token has expired, regenerate the JWT API keys. Refer to the *4G & 5G Onyx API Security with JWT Application Note*.
7. Test in incognito mode — Onyx Portal SSO requires third-party cookie support. If login succeeds in incognito mode, the issue is browser-specific: Clear the cookies and cache for *portal.gxc.io* in the user's regular browser.\
If login still fails in incognito mode, test from a different device or network — This isolates whether the issue is specific to the user's browser/device/network (for example, a captive portal, DNS issue, or corporate proxy blocking portal.gxc.io) versus a problem with the Onyx Portal service itself or the SSO/IdP integration. If login also fails from a different device and network, the cause is more likely server-side (Onyx Portal availability or IdP connectivity) rather than client-side.
**Resolution**
The issue is resolved when the user successfully logs in and reaches the Onyx Portal Dashboard.
**Escalation**
Escalate to GXC Technical Support if renewing the SAML certificate or reconfiguring the IdP does not restore user access.
If the message "*You have exhausted your MFA backup codes. Please contact GXC Technical Support for assistance.*" is displayed, instruct the user to click the **Technical Support** link in the message to open the Onyx Support Portal and create a support ticket.
Provide the following information:
* SAML error message (if SSO-related)
* IdP type and version
* Onyx Portal version
* Whether the issue affects a single user or all users
**Reference**
* *4G & 5G Multi-Factor Authentication Application Note*
* *4G & 5G Onyx Portal Integration with Customer IdP Application Note*
* *4G & 5G Onyx API Security with JWT Application Note*
Not Receiving User Account Activation Emails
**Symptoms**
A newly added Onyx Portal user does not receive the account activation email and cannot complete account setup.
**Indicators**
* The user reports that the activation email was not received.
* The user account status is **Verification Pending**.
* The user cannot complete account activation or sign in to the Onyx Portal.
**Possible Causes**
* The account activation email was delivered to the user's Spam or Junk folder.
* An incorrect email address was entered when the user account was created.
* The Onyx Portal email notification service is experiencing a delivery issue.
* The recipient's email system is blocking or filtering account activation emails.
**Actions**
1. Verify the user's email address — In **Administration** > **Users** tab, verify that the user's email address is correct. A typographical error entered during account creation is the most common cause of this issue.
2. Check the Spam and Junk folders — Verify if the account activation email, sent from ** with the subject *"Email Verification and Password Creation Link,"* was not delivered to the **Spam** or **Junk** folders. If necessary, add ** to the organization's allow list.
3. Resend account activation email — In **Administration** > **Users** tab, locate the user account and use the **Resend Activation Email** option, if available. If the option is unavailable, contact GXC Technical Support to request that the activation email be resent.
**Resolution**
The issue is resolved when the user receives the account activation email, activates the account, creates a password, and successfully signs in to the Onyx Portal.
**Escalation**
Escalate to GXC Technical Support if the activation email is not received after verifying the email address, checking the Spam or Junk folders, and resending the activation email. Provide the following information:
* User's email address
* Onyx Portal account name
* Date and time the user account was created
## Onyx Portal Operations & Permissions
This section covers issues with administrative operations caused by user permissions, backend service errors, or Onyx Edge connectivity.
Unable to Perform Operations in Onyx Portal
**Symptoms**
A user is logged in to the Onyx Portal, but one or more operations fail (for example, adding or modifying an AP configuration, generating an Analytics report, or pushing configuration changes to an Onyx Edge).
**Indicators**
* An operation fails silently or returns an error message in the Onyx Portal UI.
* Browser Developer Tools (**Console** or **Network** tab) display **4xx** or **5xx** API errors when the operation is repeated.
* Onyx Edge Online Status is red, indicating that the Onyx Portal cannot communicate with the Onyx Edge.
**Possible Causes**
* The user's RBAC role does not permit the requested operation, and the user receives a Forbidden error.
* The Onyx Portal backend API returns **4xx** or **5xx** errors while processing the request.
* The Onyx Portal cannot communicate with the Onyx Edge because management-plane connectivity is unavailable.
* The user's Onyx Portal session has expired. For UI sessions, the user is automatically logged out. For API access, the client must use the refresh token to obtain a new access and refresh token pair.
* Browser cache, extensions, or compatibility issues prevent the Onyx Portal UI from updating correctly.
* The Onyx Edge software version is incompatible with the Onyx Portal after a partial upgrade.
**Actions**
1. Verify user role and permissions — In **Administration** > **Users** tab, verify the user's assigned role and confirm that it includes permission to perform the requested operation. Supported user roles are: SUPER\_ADMIN, ADMIN, and VIEWER.
2. Verify user account status — In **Administration** > **Users** tab, verify that the user's account status is Verified. If the account is Suspended, Password Expired, or otherwise not Verified, resolve the account status first — see [*Unable to Log in to Onyx Portal* ](#unable-to-log-in-to-onyx-portal)for the full account-status checklist and recovery steps. A user with an invalid account status may still hold a valid session token temporarily, which can cause operations to fail intermittently rather than block login outright.
3. Check Onyx Edge management connectivity — In the **Onyx Edge** summary page, verify that the affected Onyx Edge's Online Status is green. If the Online Status is red, restore management-plane connectivity before attempting further Onyx Portal operations.
4. Capture browser console and network errors:
1. Open the browser **Developer Tools** (**F12**).
2. Select the **Console** and **Network** tabs.
3. Repeat the failed operation.
4. Review the results for any **4xx** or **5xx** API responses.
5. Refresh the user session:
1. Sign out of the Onyx Portal.
2. Clear the browser cache.
3. Sign in again.
If the operation succeeds after signing in again, the issue was caused by an expired session token.
6. Test in incognito mode or a different browser:
* Repeat the failed operation in an incognito/private browsing session or in a different supported browser.
* If the issue does not occur, clear the cache and cookies in the original browser, then retry the operation.
7. Verify software version compatibility — Review the applicable *Onyx Release Notes* to verify that the Onyx Portal and Onyx Edge software versions are compatible.
**Resolution**
The issue is resolved when the requested operation completes successfully, and the expected configuration or administrative change is reflected in the Onyx Portal.
**Escalation**
Escalate to GXC Technical Support if API errors continue after verifying user permissions, refreshing the session, and confirming Onyx Edge connectivity. Provide the following information:
* Browser HAR file captured during the failed operation
* Onyx Portal version
* Onyx Edge version
* The failed operation
* Complete error message displayed
## Alerts & Notifications
This section covers issues with receiving Onyx Portal alert notifications.
Not Receiving Alert Notifications
**Symptoms**
Alert notification emails are not received, or email notifications stop for an alert that remains active.
**Indicators**
* An alert is visible in **Alerts** > **Active Alerts**, but no corresponding email notification is received.
* Email notifications that were previously received stop for a specific alert or for all alerts.
* The alert remains active in the Onyx Portal without any corresponding email notification.
**Possible Causes**
* No receiver is configured for the affected alert severity level. Alert notification emails are sent only to receivers configured for the corresponding alert severity level.
* Email notifications are disabled for the applicable alert rule.
* The alert instance is muted. Muting suppresses hourly repeat emails and the cleared notification for that specific alert instance.
* The recipient's email system is blocking or filtering notification emails.
**Actions**
1. Verify the alert receiver configuration — In **Alerts** > **Receivers** tab, verify that a receiver is configured for the affected alert severity (Critical, Major, Minor, Info, Notice, or Warning). If no receiver is configured for the affected severity, email notifications are not sent.
2. Verify the alert rule notification settings — In **Alerts** > **Alert Rules** tab, verify that the notification option is enabled for the applicable predefined alert.
3. Verify whether the alert instance is muted — In **Alerts > Active Alerts**, check whether the **Mute Alert** toggle is on for the affected alert instance. If it's on, hourly repeat emails and the cleared notification for that alert instance are suppressed. To resume notifications, set the toggle to off.
4. Check Spam and Junk folders — Verify that the notification email was not delivered to the receiver's Spam or Junk folder. If necessary, add the sender domain to the organization's allow list.
**Resolution**
The issue is resolved when alert notification emails are received within the expected timeframe whenever a qualifying alert is generated.
**Escalation**
Escalate to GXC Technical Support if receivers and alert rules are configured correctly, the alert is not muted, and email notifications are still not received. Provide the following information:
* Screenshot of the **Alerts** > **Receivers** tab showing the configured recipients and alert severity levels.
* Screenshot of the **Alerts** > **Alert Rules** tab showing the notification settings.
* Name and severity of the affected alert.
## Monitoring & Reporting
This section covers issues with viewing logs, analytics, and operational data.
Logs Not Available in Onyx Portal
**Symptoms**
Log entries are unavailable for an Onyx Edge or AP, or log queries fail to return results.
**Indicators**
* The **Logs** tab displays "**No data**" for the selected time range.
* Log queries fail, return an error, or time out.
* Expected log entries are not displayed for the selected equipment.
**Possible Causes**
* The selected log query time range exceeds the supported seven-day query window.
* The Onyx Edge is offline and cannot provide log data.
**Actions**
* Verify the Onyx Edge is online — In the Onyx Edge summary page, verify that the affected Onyx Edge's Online Status is green. If the Onyx Edge is offline, restore connectivity before attempting to retrieve logs.
* Verify the selected time range — In the Onyx Edge details page > **Logs** tab, or in the AP details page > **Logs** tab, select the **NR** or **Core** radio button. Verify that the selected time range is within the last seven days and does not exceed the seven-day query window.
**Resolution**
The issue is resolved when the requested log entries are successfully displayed for the selected equipment and time range.
**Escalation**
Escalate to GXC Technical Support if the Onyx Edge is online, the selected time range is valid, and log entries are still unavailable. Provide the following information:
* Onyx Edge name
* Onyx Edge version
* Screenshot of the Logs tab showing the selected equipment, time range, and any error message or empty results
Analytics Graphs Showing No Data
**Symptoms**
One or more Onyx Portal analytics dashboards do not display the expected metrics.
**Indicators**
* The **Analytics** page displays "**No data**" for the selected equipment or time range.
* Graphs are displayed but remain flat at zero.
* Expected analytics metrics are not displayed for the selected equipment or subscriber.
**Possible Causes**
* The Onyx Edge is not connected to the Onyx Portal, preventing analytics data from being collected.
* The selected time range does not contain analytics data or exceeds the supported 90-day retention period.
* Dashboard filters are configured for equipment or subscribers that have no associated analytics data.
* No UE were active during the selected time period. Some analytics metrics are generated only while subscriber sessions are active.
* The Onyx Edge software version does not support the selected analytics metric.
* The selected KPI is supported only on specific AP models or network types. For example:
* 5G-only KPIs are available only for 5G deployments.
* 4G-only KPIs are available only for 4G deployments.
* Per-subscriber radio metrics are available in the Subscriber details page > **Analytics** tab rather than the main Analytics dashboard.
**Actions**
1. Verify Onyx Edge connectivity — In the Onyx Edge summary page, verify that the affected Onyx Edge's Online Status is green. If the Onyx Edge is offline, restore connectivity and allow approximately 2–5 minutes for analytics data collection to resume.
2. Verify the selected time range:
* Select a broader time range (for example, **Last 24 Hours** or **Last 7 Days**) and refresh the dashboard.
* Analytics data is retained for up to 90 days. Custom queries cannot exceed the 90-day retention period.
* If the most recent data point is zero, wait a few minutes and refresh the dashboard.
3. Clear the dashboard filters — Reset the AP, Subscriber, and Site filters to **All**. A filter set to a decommissioned AP or inactive subscriber returns no analytics data.
4. Verify subscriber activity — In the Subscriber summary page, verify whether any UE were active during the selected time period. Throughput and radio analytics are generated only while subscriber sessions are active.
5. Verify the selected analytics metric — Confirm that the selected AP model and network type support the requested KPI.
* 5G-only KPIs (Cell SRS SNR, DL/UL BLER, RRC Success %, RACH Attempts, NGAP Dropped Connections) return no data when a 4G network is selected.
* 4G-only KPIs (GPS Signal Availability, Dropped Call Rate) return no data when a 5G network is selected.
* Per-subscriber radio metrics (DL RSRP, DL/UL MCS, DL/UL BLER, DL/UL Rank) are available in the Subscriber details page > **Analytics** tab > **Plots** tab > **5G Only KPIs**, rather than in the main Analytics dashboard.
6. Verify the Onyx Edge software version — Some analytics KPIs are available only in specific software releases. Compare the installed software versions with the applicable *Onyx Release Notes*.
* (4G) In the Onyx Edge details page > **Overview** tab > **Onyx Edge Details** section, verify the **Version** parameter.
* (5G) In the Onyx Edge details page > **Overview** tab > **Onyx Edge Details** section, verify the **NR Version** and **Core Version** parameters.
**Resolution**
The issue is resolved when the selected analytics dashboard displays the expected metrics for the selected equipment, subscriber, and time range.
**Escalation**
Escalate to GXC Technical Support if analytics data remains unavailable after verifying Onyx Edge connectivity, dashboard filters, supported KPIs, software versions, and the selected time range. Provide the following information:
* Onyx Portal version
* Onyx Edge version
* Screenshot of the affected Analytics dashboard showing the selected equipment, time range, applied filters, and missing metrics
### Subscriber Management
This section covers issues with subscriber administration and network assignment.
Unable to Add a New Subscriber
**Symptoms**
A new subscriber cannot be added to the selected network.
**Indicators**
* The **Add Subscriber** option is unavailable.
* The required SIM or eSIM is not available for selection.
* The subscriber cannot be created.
**Possible Causes**
* The required SIM or eSIM has not been provisioned.
* No unassigned SIMs or eSIMs are available for the selected network.
* The user does not have sufficient permissions to manage subscribers.
**Actions**
1. Verify user permissions — Confirm that the user account has permission to manage subscribers.
2. Verify SIM availability — Confirm an unassigned SIM or eSIM is available for the selected network.
3. Contact GXC Technical Support — If no unassigned SIMs or eSIMs are available, contact GXC Technical Support to provision additional subscriber credentials.
**Resolution**
The issue is resolved when the subscriber is successfully created and assigned to the selected network.
**Escalation**
Escalate to GXC Technical Support if subscriber provisioning cannot be completed or additional SIMs or eSIMs are required. Provide the following information:
* Network name
* Subscriber details
* Required SIM type (Physical SIM or eSIM)
Subscriber Cannot Be Assigned to the Correct Network
**Symptoms**
The subscriber appears in the Onyx Portal but cannot access the intended network.
**Indicators**
* The subscriber is assigned to an incorrect network.
* The intended network is unavailable during subscriber assignment.
**Possible Causes**
* The SIM or eSIM is assigned to a different network.
* The subscriber requires reassignment to the intended network.
* The selected APN is not available in the network.
**Actions**
1. Verify the subscriber's current network — In the Subscriber details page, verify that the subscriber is assigned to the intended network.
2. Verify the target network availability — Confirm that the intended network is available for subscriber assignment.
3. Verify APN availability — Confirm that the required APN is available and correctly configured in the selected network.
**Resolution**
The issue is resolved when the subscriber is assigned to the intended network.
**Escalation**
Escalate to GXC Technical Support if the subscriber cannot be assigned to the intended network. Provide the following information:
* Subscriber IMSI
* Current network
* Target network
Subscriber Cannot Be Deleted
**Symptoms**
A subscriber cannot be deleted from the Onyx Portal.
**Indicators**
* The delete subscriber option is unavailable.
* The subscriber remains assigned to a network.
**Possible Causes**
* The subscriber is currently assigned to an active network.
* The user account does not have sufficient permissions to delete subscribers.
**Actions**
1. Verify the subscriber assignment — Verify that the subscriber is no longer required.
2. Verify user permissions — Confirm that the user account has permission to delete subscribers.
**Resolution**
The issue is resolved when the subscriber is successfully deleted.
**Escalation**
Escalate to GXC Technical Support if the subscriber cannot be deleted after verifying the subscriber assignment and user permissions. Provide the following information:
* Subscriber IMSI
* Subscriber name
* Network name
### SIM/eSIM Activation & Connectivity
This section covers issues with SIM/eSIM activation and subscriber connectivity.
Subscriber Cannot Attach After SIM/eSIM Activation
**Symptoms**
The subscriber has been provisioned, but the UE cannot attach to the network.
**Indicators**
* The subscriber status remains disconnected.
* The UE displays "No Service" or "Searching."
**Possible Causes**
* The subscriber is inactive.
* The UE is configured with an incorrect PLMN or APN.
* IMEI verification prevents the UE from attaching.
**Actions**
1. Verify the subscriber status — In the Subscriber details page, verify that the subscriber status is active.
2. Verify the UE configuration — Confirm that the UE is configured with the correct PLMN and APN.
3. Verify IMEI verification — If IMEI verification is enabled, verify that the UE IMEI matches the IMEI configured for the subscriber.
**Resolution**
The issue is resolved when the UE successfully attaches to the network and the subscriber status is updated accordingly in the Onyx Portal.
**Escalation**
Escalate to GXC Technical Support if the subscriber cannot attach after verifying the subscriber status. Provide the following information:
* Subscriber IMSI
* UE IMEI
* Subscriber details
* APN configuration
eSIM Activation Issues
**Symptoms**
An eSIM cannot be installed or activated on the UE.
**Indicators**
* The QR code cannot be scanned.
* The eSIM installation fails.
* The eSIM is installed successfully, but the UE cannot attach to the network.
**Possible Causes**
* The eSIM profile was not installed successfully.
* The UE does not support the required eSIM functionality.
* The eSIM profile has not synchronized correctly.
* The eSIM is already enabled/activated on another UE and has not been deleted from that UE. An eSIM cannot be used on more than one UE at the same time.
**Actions**
1. Verify the QR code — Confirm that the correct QR code is being used for the intended subscriber.
2. Verify device compatibility — Confirm that the UE supports eSIM and meets the deployment requirements.
3. Retry the eSIM installation — Remove any incomplete eSIM profile from the UE, then repeat the eSIM installation using the same QR code.
4. Verify the eSIM is not active on another UE — If the eSIM was previously used on a different UE, it must first be deleted from that UE. A GXC Administrator must then reset the eSIM before it can be activated on the new UE.
**Resolution**
The issue is resolved when the eSIM is successfully installed and the UE successfully attaches to the network.
**Escalation**
Escalate to GXC Technical Support if the eSIM installation or activation continues to fail after verifying the QR code, device compatibility, and installation procedure. Provide the following information:
* Device make and model
* Subscriber IMSI
* ICCID (if available)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.gxc.io/docs/troubleshooting/onyx-troubleshooting-guide/operations-and-administration-issues.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.