> For the complete documentation index, see [llms.txt](https://docs.userlane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.userlane.com/deployment/rollout/roll-out-the-extention/troubleshoot-the-extension.md).

# Troubleshoot the extension

Diagnose and resolve extension activation failures including authentication errors, configuration mismatches, content security policy blocks, and the extension not appearing.

This page helps you find and fix the reason the browser extension is not working. Work through the checks in order.

{% hint style="warning" %}
**Prerequisites.** The extension has been distributed through group policy or mobile device management (MDM). If the extension has not been distributed yet, start with [Roll out the extension](/deployment/rollout/roll-out-the-extention.md).

Some checks require the browser's developer tools (F12 on Windows, Cmd+Option+I on macOS). For single sign-on (SSO) errors, you also need access to the identity provider (IDP) administration console.
{% endhint %}

## Diagnostic sequence

Each step describes what to look for, how to check, and how to resolve.

{% stepper %}
{% step %}

#### Confirm the application URL is registered

The application must be listed in the Userlane portal. If the page URL does not match any registered application URL, the extension does not activate.

Open the portal and go to **Settings** > **Application URLs**. Check that the application appears in the list and that the URL matches the address bar of the page. See [Set up the application URL](/getting-started/first-steps-in-the-portal/set-up-the-application-url.md).

If the URL was added or changed recently, allow up to one hour for the extension to pick up the update.
{% endstep %}

{% step %}

#### Ensure Userlane is enabled in the portal

Even when the extension is installed and the application URL is registered, Userlane does not appear unless it is switched on for that application in the portal.

Open the portal and go to **Settings** > **General Settings**. Confirm that the Userlane toggle is enabled. When the toggle is off, nothing is delivered to end users on any page where the extension or snippet is active.

If you just turned the toggle on, refresh the application page in the browser. The change takes effect immediately.
{% endstep %}

{% step %}

#### Check the extension configuration values

The extension needs three values delivered through managed storage[^1]: `companyId`, `companyIntegrity` (the integrity token), and `region`. If any value is missing or wrong, the extension does not activate.

Right-click the Userlane extension icon and select **Options**. Open **Managed Storage**. Check that all three values are present and that none is marked as an error.

If no data appears at all, the browser has not received the extension policy. Go back to [Roll out the extension](/deployment/rollout/roll-out-the-extention.md) and confirm the policy file is applied.
{% endstep %}

{% step %}

#### Check for content security policy (CSP) blocks

If the application has a strict content security policy (CSP), the browser may block requests to Userlane. This happens most often when the SSO window mode[^2] is set to **Iframe**.

Open the browser console (F12, then the **Console** tab). Look for errors that mention "Content Security Policy," "frame-src," or "Refused to load."

If CSP errors appear, share the required host list with the IT team. The full list is in [Environment prerequisites](/deployment/rollout/environment-prerequisites.md).

{% hint style="warning" %}
**Microsoft Entra ID does not support Iframe mode.** If the identity provider is Entra ID (formerly Azure AD) and the SSO window mode is set to **Iframe**, authentication fails regardless of CSP settings. Switch to **Inactive Tab** or **Active Tab**.
{% endhint %}
{% endstep %}

{% step %}

#### Check extension URL restrictions

If the IT team has limited which URLs the extension can run on, the Userlane domain must be on the allow list.

Add `*://*.userlane.com/*` to the extension's URL allow list in the group policy or MDM profile.
{% endstep %}

{% step %}

#### Confirm IDP group membership (SSO deployments)

The end user must belong to the correct group in the identity provider (for example, Entra ID, Active Directory Federation Services (ADFS), or Google Workspace). If the user is not in the group, SSO authentication fails silently and the extension does not activate.

Check the IDP and confirm the user is a member of the group configured for Userlane SSO.
{% endstep %}

{% step %}

#### Check for multiple login sessions

If a user has more than one login to the identity provider, SSO authentication cannot select which identity to use, and the extension cannot prompt the user to choose.

To test, temporarily set the SSO window mode to **Active Tab**. If the authentication page opens and asks the user to select an account, that user cannot authenticate silently with the extension.

Ensure each affected user has a single active login session, or exclude multi-login users from the extension rollout.
{% endstep %}

{% step %}

#### Check third-party cookie settings

Some browsers block third-party cookies by default. Userlane needs cookies from its own domain to work.

To test, temporarily allow all cookies in the browser settings. If Userlane appears after that, add these two domains to the browser's third-party cookie allow list:

* The application domain (the URL where Userlane runs)
* `[*.]userlane.com`

Then restore the default cookie settings.
{% endstep %}

{% step %}

#### Disable ad blockers and check antivirus settings

Ad blockers and some antivirus software can block Userlane's network requests or cookie storage. Temporarily disable the ad blocker or add a Userlane exception to test.

If disabling the ad blocker resolves the problem, add the Userlane domain to the ad blocker's allow list.
{% endstep %}
{% endstepper %}

When the checks pass, Userlane appears in the application and the end user can interact with content. If the problem persists, continue to the SSO error table or the log export section below.

## SSO authentication errors

When SSO is configured, authentication errors can appear in the extension or during the SSO test. The table below lists known error messages with their cause and fix.

To test the SSO connection, open the SSO settings page in the portal and select **Test SSO**. The test runs the full SSO flow and redirects to the browser extension on success. See [End-user single sign-on](/deployment/rollout/end-user-single-sign-on.md).

<table><thead><tr><th width="191.4140625">Error</th><th>Cause</th><th>Resolution</th></tr></thead><tbody><tr><td>Invalid CompanyId</td><td>The <code>companyId</code> value in the extension policy does not match the value in the portal.</td><td>Confirm the company ID with the Userlane team.</td></tr><tr><td>Invalid Signature</td><td>The Security Assertion Markup Language (SAML) certificate has expired or does not match the certificate uploaded in the portal.</td><td>Renew the certificate in the IDP. Upload the new certificate in the portal SSO settings. Only one certificate can be active at a time. Remove the expired certificate first.</td></tr><tr><td>Error status code 500</td><td>Server-side error, often caused by a datatype mismatch in the SSO configuration.</td><td>Contact Userlane support with the full error response.</td></tr><tr><td>PEM_read_bio_PUBKEY failed</td><td>The certificate uploaded to the portal is malformed: missing characters, extra whitespace, or incorrect encoding.</td><td>Re-export the certificate from the IDP metadata XML file and re-upload it to the portal.</td></tr><tr><td>Outdated certification</td><td>The certificate has expired.</td><td>Upload a new, active certificate. Remove the expired one first.</td></tr><tr><td>Invalid certificate format</td><td>The certificate text contains formatting errors such as blank spaces, missing content, or extra characters.</td><td>Review the certificate text character by character. Re-paste from a clean export of the IDP metadata.</td></tr><tr><td>422</td><td>The SSO trust relationship has not been established between the IDP and Userlane.</td><td>Configure the SSO trust for Userlane in the IDP.</td></tr><tr><td>401 (repeated login loop)</td><td>The SSO session token has expired or the SSO configuration was changed after the session started. The extension shows an empty box or prompts login repeatedly.</td><td>Contact Userlane support immediately with a screenshot of the network request and the error detail.</td></tr></tbody></table>

**IDP login page opens but no user appears in the portal.** The entry point URL is likely wrong. Check that it contains "SAML" and matches the entry point URL in the IDP metadata XML file.

**A separate window opens asking to log in again.** Security software may be blocking the authentication response, or the user may not be connected to the organization's network. Check both before escalating.

## Export extension logs

The extension stores diagnostic logs that can help Userlane support investigate the problem.

1. Right-click the Userlane extension icon in the browser toolbar.
2. Select **Options**.
3. Open the troubleshooting or log section and export the logs.

Include the exported file in the support request together with a description of the problem and the checks already tried.

## Still not working?

If none of the checks on this page resolved the problem, email <support@userlane.com> or contact your Customer Value Manager directly. Include as much of the following as possible:

* Which step in the diagnostic sequence was reached
* The extension log export, or a screenshot of the browser console
* The browser name and version
* The extension version
* Whether the problem affects one user or all users

## Relevant articles

{% content-ref url="/pages/ZbAA5aBZMukn2qqLRZji" %}
[Roll out the extension](/deployment/rollout/roll-out-the-extention.md)
{% endcontent-ref %}

{% content-ref url="/pages/SRW9iMERFNl0SSjAfJnd" %}
[Environment prerequisites](/deployment/rollout/environment-prerequisites.md)
{% endcontent-ref %}

{% content-ref url="/pages/IkbYytjTIP1b0c4ZNCbM" %}
[End-user single sign-on](/deployment/rollout/end-user-single-sign-on.md)
{% endcontent-ref %}

{% content-ref url="/pages/x0VOtqZaqLMPxH6L3eGw" %}
[Contact and escalation](/support/contact-and-escalation.md)
{% endcontent-ref %}

## FAQ

<details>

<summary>How does Userlane retry after an SSO authentication failure?</summary>

The extension uses exponential backoff. It retries after 2 minutes, then 4, then 8, and keeps doubling. Restarting the browser or reinstalling the extension resets the retry cycle.

</details>

<details>

<summary>Can the extension and the JavaScript snippet run on the same page?</summary>

No. Only one method should be active per page. If both are loaded, behavior is unpredictable. Remove one before troubleshooting.

</details>

<details>

<summary>The extension icon is colored but the Assistant is not visible. What is wrong?</summary>

The extension is running, but content may be hidden by targeting rules, audience membership, or publish state. Check the content visibility settings in the portal for the affected application. See [Targeting](/assistance/content-operations/targeting.md).

</details>

<details>

<summary>The extension was just installed but Userlane is not appearing. How long does activation take?</summary>

After the policy is applied and the browser is restarted, activation should happen within minutes. If the application URL was recently added to the portal, allow up to one hour for the change to reach the extension.

</details>

[^1]: Managed storage is a browser mechanism that lets IT teams push configuration values to an extension through group policy or MDM, without end-user interaction.

[^2]: The SSO window mode controls how the extension opens the identity provider's login page: invisibly in an iframe, in a background tab (Inactive Tab), or in a focused tab (Active Tab).


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.userlane.com/deployment/rollout/roll-out-the-extention/troubleshoot-the-extension.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.