Troubleshooting

Use this section to diagnose and resolve common issues with Workspace ONE Browser Plugin. Match your symptom to the relevant section, follow the steps, and use the Quick Reference table for a summary of known issues.DEL

Extension Architecture at a Glance

The extension relies on four layers that must all function together for device lookup to work:

Authentication Fails

Symptom: The extension displays "Login failed. Please check your credentials and try again."

Steps to resolve:

1. Confirm the OAuth client matching your browser (itsm-chrome-extension or itsm-edge-extension) is registered with redirect URI https://<extension-id>.chromiumapp.org.
2. Double-check the Hub Services URL entered on the options page.
3. Re-authenticate from the options page after changing any of the above.

---

Device Details Do Not Load After Login

Symptom: Authentication succeeds but device details still do not appear, or you see a message about a missing or invalid admin token.

Likely causes:

• The /catalog-portal/services/auth/adminTokens API call failed after OAuth login.
• The EUC_XSRF_TOKEN or HZN cookies could not be set because the Hub Services URL uses HTTP instead of HTTPS.
• The access token is expired or malformed.

Steps to resolve:

1. Open the extension Options page and click Re-Authenticate to trigger a fresh login and admin token fetch.
2. Confirm that the Hub Services URL starts with https://. An HTTP URL prevents the extension from setting secure cookies.
3. Open the browser DevTools and navigate to Application > Cookies for the Hub Services domain. Look for EUC_XSRF_TOKEN, HZN, and ADMIN_CONSOLE_CONTEXT. If they are absent, the cookie setup step failed.
4. In chrome://extensions, click the extension name, then click Service Worker > Inspect to check the service worker console for cookie permission errors.
5. Verify that the cookies permission is listed under chrome://extensions for this extension.

---

Missing or Invalid Server URL or Device Identifier

Symptom: The side panel displays "Missing or invalid server URL" or "Missing or invalid device identifier."

Likely causes:

• You opened the extension side panel before completing the initial Options page setup.
• Chrome storage was cleared (for example, after reinstalling the extension or if storage quota was exceeded).
• You edited the ITSM Configuration form but did not click Save Configuration.

Steps to resolve:

1. Open the extension Options page.
2. Enter the Hub Services URL and OAuth Client ID and click Authenticate.
3. Enter the ITSM URL and Device Identifier (XPath) and click Save Configuration. Wait for the "Configuration saved successfully" message before closing the Options page.
4. Reopen the extension side panel.
5. To verify that the configuration is stored, open the browser DevTools > Application > Local Storage for chrome-extension://<your-extension-id>. Confirm that authState and itsmConfig keys are present.
6. If the configuration keeps disappearing, check whether your browser profile or enterprise policy disables local storage for extensions, or whether you are running the extension in Incognito mode with storage restrictions.

---

Device Identifier Not Found on the Page

Symptom: The extension displays "Device identifier not found on the page" or a validation error in device details.

Steps to resolve:

1. The field expression (XPath) for that ITSM page may no longer match the page's current markup — this needs to be fixed in the central ITSM system configuration, not in the extension.
2. Use the manual search fallback in the meantime.

---

Context Menu Lookup Does Not Open the Side Panel

Symptom: You right-click a serial number, select "Lookup in Omnissa," but the extension side panel does not open.

Likely causes:

• chrome.action.openPopup() is restricted in some Chrome configurations when called from a non-user-gesture context.
• The background service worker stored the serial number but could not open the side panel, triggering the browser's fallback alert.
• The selected text was empty or contained only whitespace.

Steps to resolve:

1. If you see the alert "Could not open the extension popup automatically," click the extension toolbar icon. The serial number is already stored and displays immediately.
2. Select only the serial number text, without any surrounding whitespace.
3. Use the right-click menu on a standard HTTPS page only. This feature does not work on chrome:// pages or the Chrome Web Store.
4. If the context menu item does not appear at all:
   • Confirm the extension is enabled in chrome://extensions.
   • Go to chrome://extensions > the extension > Service Worker > Inspect. If the worker shows "Inactive," click Inspect to wake it up and look for errors related to contextMenus.
5. If the context menu is lost after a browser restart, disable and re-enable the extension. The service worker re-creates the context menu automatically on startup.

---

Device Lookup Returns an HTTP Error

Symptom: Device details fail to load and the side panel displays an HTTP error code.

For 401 Unauthorized:

1. On the extension Options page, click Re-Authenticate to obtain a fresh token.
2. Retry fetching device details.
3. If 401 persists after re-authentication, the OAuth client may be misconfigured on the server side. Review the client configuration in Access Console.

For 403 Forbidden:

1. Log in to the Workspace ONE UEM console with the same credentials used for OAuth.
2. Confirm the account has at least read access to devices in the enrolled organization group.
3. Contact your Workspace ONE UEM administrator to review role permissions.

For 404 Not Found:

1. Confirm that the serial number on the ITSM page exactly matches the serial number enrolled in Workspace ONE UEM. The value is case-sensitive, and extra spaces cause a mismatch.
2. Verify that the Hub Services URL points to the correct UEM tenant.
3. Search for the device directly in the Workspace ONE UEM console to confirm it is enrolled.

For 500 or Network Errors:

1. Confirm the Hub Services server is online and reachable from your network.
2. Test the API by opening the following URL in a browser tab:

   <Hub Services URL>/catalog-portal/services/console/api/devices/summary?searchBy=serialNumber&id=TEST
   

3. Check your network proxy settings. Corporate proxies may block outbound requests from browser extensions.

---

Device Actions Fail

Symptom: A device action (Find Device, Lock Device, Sync, or Clear Passcode) fails or shows an error.

Likely causes:

• Device details have not loaded, so the device UDID is unavailable.
• For Lock Device on Apple macOS, the required six-digit numeric PIN was not entered or is invalid.
• The action API call failed with an authentication error.
• The action is not supported for this device's platform or enrollment type.

Steps to resolve:

1. If you see "Cannot perform this action because the device identifier is unavailable," click Refresh or Fetch Device Details and wait for device details to load before attempting the action.
2. For Lock Device on Apple macOS: Enter exactly six numeric digits when prompted. The device user needs this PIN to unlock the device after the lock command.
3. If the action returns an error, check the Workspace ONE UEM server logs using the device UDID and action type. The extension sends a POST request to:

   /catalog-portal/services/console/api/devices/actions/{udid}/{action}
   

4. If the action fails with a 401 error, re-authenticate as described in Device Lookup Returns an HTTP Error.
5. Some actions, such as Clear Passcode, are available only for enrolled, supervised, or managed devices. Verify the device's enrollment and supervision status in the device details panel.

---

Popup Says the Page Isn't Supported, or Shows No Data

Symptom: The side panel displays "The current tab is not supported by configuration" or shows no data.

Steps to resolve:

1. Confirm the tab's host is one of the centrally-configured ITSM systems.
2. Make sure you've granted the per-site permission for that host.
3. Open the side panel on the specific record/details page where the device identifier appears, not a list or search page.

---

Host Permission Prompt Keeps Reappearing

Symptom: The side panel repeatedly shows "Enable Omnissa DEX on this ITSM portal?" even after you have previously clicked Enable.

Likely causes:

• You clicked Cancel in the Chrome permission dialog and the permission was not granted.
• Host permissions were cleared when the extension was updated or reinstalled.
• An enterprise Chrome policy restricts optional extension permissions.

Steps to resolve:

1. Click Enable in the side panel. Chrome opens a permission dialog asking to grant access to that ITSM site's origin.
2. In the Chrome dialog, click Allow. Clicking Cancel does not grant the permission and the prompt reappears on the next page load.
3. To verify that the permission is stored, go to chrome://extensions > the extension > Details > Site access.
4. If permissions disappear repeatedly, check whether an enterprise Chrome policy is restricting optional extension permissions. Contact your IT administrator.

---

Extension Appears Broken After an Update

Symptom: After a Chrome update or extension update, the extension stops working, the context menu disappears, or stored configuration is no longer available.

Likely causes:

• The background service worker was invalidated after the update.
• Context menus are not automatically preserved across extension updates.
• Stored data from the previous version may be incompatible with the new version.

Steps to resolve:

1. Go to chrome://extensions and click Reload (the circular arrow icon) on the extension. The service worker restarts and the context menu re-creates automatically.
2. If the extension still does not work correctly, click Remove and reinstall it from the Chrome Web Store or Edge Add-ons store.

Important: Removing the extension clears all stored configuration. After reinstalling, you must re-enter the Hub Services URL, OAuth Client ID, ITSM URL, and Device Identifier XPath, and then authenticate again.

---

UI Text Is Missing or Shows Translation Keys

Symptom: The extension side panel or Options page displays raw translation keys such as options.server.url instead of readable labels.

Likely causes:

• The internationalization file (assets/i18n/en.json) failed to load.
• The extension was loaded from an incomplete build where the assets/ folder was not bundled.

Steps to resolve:

1. Open the extension side panel or Options page and press F12 to open DevTools > Network tab.
2. Reload the page and look for a request to assets/i18n/en.json. A 404 response indicates the build is incomplete.
3. If you are using a development build (running npm start), confirm the development server is running.
4. For a production install, verify that the extension package contains assets/i18n/en.json. Check via chrome://extensions > the extension > Details > Extension package.

---

Side Panel Opens to a Blank White Page

Symptom: Clicking the extension icon opens the side panel, but it shows only a blank white page.

Likely causes:

• Angular failed to bootstrap because of a JavaScript error during initialization.
• The extension was not built before loading—main.js or index.html is absent.
• A Content Security Policy (CSP) violation blocked script execution.

Steps to resolve:

1. Right-click inside the side panel and select Inspect, or open the side panel DevTools from chrome://extensions > the extension > Inspect popup.
2. In the Console tab, look for red errors. Common causes include:
   • Cannot read properties of undefined — a service failed to initialize.
   • CSP errors — a third-party script violated the extension's content security policy.
3. In the Network tab, look for red (failed) resource requests.
4. If the extension was loaded from source, run npm run build and reload the unpacked extension from chrome://extensions.

---

Device Details Could Not Be Loaded

Symptom: The side panel shows "Device details could not be loaded" without a specific HTTP error code.

Likely causes: This error most commonly occurs in enterprise environments where browser or network controls restrict outbound requests from extensions.

Steps to resolve:

1. Open the side panel DevTools > Network tab. Look for the failed request (the error originates around device.service.ts:346) and note the status code and error message.
2. Open chrome://policy and review enterprise policies for URL blocking, cookie restrictions, and extension permissions.
3. Check whether the required cookies (EUC_XSRF_TOKEN, HZN) are written before the fetch occurs (code path starts at device.service.ts:98).
4. Compare the behavior on an unmanaged browser profile with a managed profile. If the error occurs only on the managed profile, an enterprise policy is the likely cause.
5. If the issue is confirmed to be policy-related, provide your security team with the timestamp, URL, status code, and blocked reason from the DevTools Network tab.

---

ITSM Configuration Fails to Load

Symptom: Login succeeds but the extension reports that ITSM plugin configuration could not be loaded.

Steps to resolve:

1. Confirm the Hub Services server is reachable.
2. Make sure the ITSM plugin configuration is available in the central server configuration.
3. After the configuration is available again, log out and back in to fetch it again.

---

Device Details Fail to Load or Time Out

Symptom: Device details fail to load or the lookup times out.

Steps to resolve:

1. Check your network or VPN connection and confirm the Hub Services/UEM server is available.
2. Use Reload in the popup to retry the device lookup.
3. If the popup reports an authentication error, re-authenticate from the options page and try again.
4. Use the manual search fallback if it is available.

---

Quick Reference: Symptoms and Likely Causes