Skip to main content

Troubleshooting

Solutions for common issues encountered when integrating the Lovina Chat SDK.

Widget Does Not Appear​

The chat bubble is not visible​

  1. Check the browser console for errors. Open developer tools and look for messages starting with [Lovina].

  2. Verify your configuration. Ensure websiteToken and baseUrl are correct:

    window.lovinaChatSDK.run({
      websiteToken: 'YOUR_WEBSITE_TOKEN', // Must match your dashboard
      baseUrl: 'https://chat.lovina.app', // Must be reachable
    });

  3. Check hideMessageBubble. If set to true, the bubble is intentionally hidden. Open the chat programmatically:

    window.$lovina.toggle('open');

  4. Check script loading order. window.lovinaSettings must be defined before calling window.lovinaChatSDK.run().

  5. Check for CSS conflicts. Ensure no styles on your page are setting z-index high enough to cover the widget (the SDK uses z-index: 2147483000).

The widget loads but shows a blank screen​

  1. Verify the baseUrl is reachable. Open {baseUrl}/widget in a new browser tab.
  2. Check for mixed content. If your site is served over HTTPS, the baseUrl must also use HTTPS.

CSP (Content Security Policy) Issues​

If your site uses a Content Security Policy, the SDK requires these directives:

frame-src https://chat.lovina.app;
script-src https://chat.lovina.app;
connect-src https://chat.lovina.app wss://chat.lovina.app;
img-src https://chat.lovina.app;

Replace https://chat.lovina.app with your actual baseUrl if you are self-hosting.

Symptoms of CSP issues​

  • Widget iframe does not load (check console for Refused to frame errors).
  • WebSocket connections are blocked (check console for Refused to connect errors).
  • Images or uploaded files do not display.

How to diagnose​

Open the browser console (F12) and filter for "Refused" or "CSP" errors. Each blocked resource will indicate which CSP directive needs updating.

CORS Errors​

CORS errors typically appear when the baseUrl is misconfigured or the server is not set up to accept requests from your domain.

Symptoms​

  • Access-Control-Allow-Origin errors in the browser console.
  • Messages fail to send with network errors.

Solutions​

  1. Verify baseUrl is correct -- it must match the server's configured origin exactly (including protocol and port).
  2. Check server CORS configuration -- the Lovina backend must allow your website's origin.
  3. Check for proxy interference -- reverse proxies (nginx, Cloudflare) may strip or modify CORS headers.

WebView Debugging​

Android​

  1. Enable WebView debugging in your app: 
    WebView.setWebContentsDebuggingEnabled(true)
  2. Connect the device via USB.
  3. Open chrome://inspect in Chrome on your computer.
  4. Select the WebView from the list to open DevTools.

iOS​

  1. Enable Web Inspector in Safari on the device: Settings > Safari > Advanced > Web Inspector.
  2. Connect the device via USB.
  3. Open Safari on your Mac, go to Develop > [Device Name] and select the WebView.

Common WebView issues​

  • File picker does not open -- See the File Upload guide for platform-specific WebView setup.
  • Cookies not persisting -- Ensure the WebView allows cookies and local storage.
  • JavaScript disabled -- Verify javaScriptEnabled is true in WebView settings.

File Upload Not Working​

Files are not uploading​

  1. Check the feature flag. Ensure file upload is not disabled:

    window.lovinaSettings = {
      features: {
        enable_file_upload: true,
      },
    };

  2. Check file size. Files must be under 10 MB each.

  3. Check file count. Maximum 5 files per message.

  4. Check accepted types. Only image/*, application/pdf, text/*, audio/*, and video/* are accepted.

File picker does not open on mobile​

On Android and iOS WebViews, the native file picker requires platform-specific configuration. See the File Upload guide for setup instructions.

Uploads fail with network errors​

  1. Check that the baseUrl supports multipart form data uploads.
  2. Verify there is no file size limit set by a reverse proxy (nginx default is often 1 MB -- you may need to increase client_max_body_size).
  3. Check for CORS issues on the upload endpoint.

Messages Are Not Sending​

  1. Check network connectivity. Open the Network tab in developer tools and look for failed requests to /sdk/chat/.

  2. Verify the websiteToken. An invalid token results in 401 responses.

  3. Enable debug mode for detailed console output:

    window.lovinaSettings = {
      features: { debug_mode: true },
    };

User Identity Not Persisting​

  1. Check cookies. The SDK stores session data in cookies. Ensure your site is not blocking or clearing cookies on navigation.

  2. Call setUser after lovina:ready. Setting the user before the widget loads has no effect:

    window.addEventListener('lovina:ready', function() {
      window.$lovina.setUser('user-123', { name: 'Jane' });
    });

Settings Not Updating​

window.lovinaSettings is read once during initialization. To change settings at runtime:

  • Use API methods: setLocale(), setColorScheme(), toggle(), etc.
  • For settings without a runtime API, call destroy() and reinitialize: 
    window.$lovina.destroy();
    window.lovinaSettings = { /* new settings */ };
    window.lovinaChatSDK.run({ websiteToken: '...', baseUrl: '...' });

Dark Mode Not Working​

  1. Check the darkMode setting. It should be 'dark' or 'auto'.
  2. If using 'auto', verify your OS is set to dark mode. The widget follows prefers-color-scheme.
  3. Runtime toggle: 
    window.$lovina.setColorScheme('dark');

Transport / Connection Issues​

The SDK supports three transport protocols with automatic fallback: WebSocket, SSE, and Long Polling. If you experience connection issues:

  1. Check firewall rules. WebSocket connections (wss://) may be blocked by corporate firewalls. The SDK will automatically fall back to SSE or long polling.

  2. Force a specific transport for debugging:

    window.lovinaSettings = {
      features: {
        enable_websocket: false,
        enable_sse: false,
        enable_long_polling: true, // Only use long polling
      },
    };

  3. Check proxy configuration. Some reverse proxies (nginx, HAProxy) require explicit WebSocket upgrade configuration.

Getting Help​

If you cannot resolve the issue:

  1. Enable debug_mode: true and reproduce the problem.
  2. Copy the console output.
  3. Note your browser, OS, and SDK version.
  4. Contact support@ailovina.com with the above information.