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.ailovina.com", // 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.ailovina.com;
script-src https://chat.ailovina.com;
connect-src https://chat.ailovina.com;
img-src https://chat.ailovina.com;

Replace https://chat.ailovina.com 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​

Symptoms​

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

Solutions​

  1. Verify baseUrl/apiUrl are correct -- they must match the intended environment's actual host (including protocol and port); a request reaching the wrong environment will look like a CORS failure.
  2. Check for proxy interference -- reverse proxies (nginx, Cloudflare) may strip or modify CORS headers.
  3. Still failing? Contact support with your websiteToken and the exact origin your site is served from -- your account may need to be configured to allow it.

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.
  • Composer overlaps the Android system nav bar -- Call enableEdgeToEdge() in your Activity's onCreate(), right after super.onCreate() and before setContentView(...). This is required for the widget's safe-area CSS to see a real inset, but it also disables Android's automatic keyboard-resize behavior -- pair it with a ViewCompat.setOnApplyWindowInsetsListener that sets your root view's bottom padding to the IME inset, so the WebView still shrinks correctly when the keyboard opens. Leave system-bar insets unhandled; the WebView needs to keep extending behind them for the safe-area CSS to work.
  • Composer is pushed off-screen by the keyboard on Flutter -- The widget already handles keyboard insets itself. Don't wrap LovinaChatWidget in your own Padding(padding: MediaQuery.viewInsetsOf(context)), and don't set resizeToAvoidBottomInset: false on a host Scaffold and compensate manually -- either one double-compensates and strands the composer a further keyboard height off-screen.

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 5 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 -- raise client_max_body_size to at least 6m, which leaves headroom above the 5 MB file limit for multipart overhead).
  3. Check for CORS issues on the upload endpoint. CORS headers must also be present on error responses (in nginx, add them with the always parameter); otherwise the browser hides a 413 and the widget can only report a generic network error.

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 colorScheme 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. SSE connections may be blocked by corporate firewalls or proxies. Ensure your network allows long-lived HTTP connections to the backend.

  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.

Which Build Is Deployed?​

If the widget's behavior doesn't match what you expect -- a fix that "should already be live," or an unexplained 400/401 that might be a stale or misconfigured deployment -- you can check exactly which build is running at a given host without opening a support ticket first:

curl https://chat.ailovina.com/build-info.json

Replace https://chat.ailovina.com with your own baseUrl if self-hosting. This returns:

{
  "version": "1.2.0",
  "gitSha": "a1b2c3d4e5f6...",
  "builtAt": "2026-03-01T12:00:00.000Z",
  "rumEnv": "production",
  "apiVersion": "v1",
  "apiUrlSource": "baked",
  "wsUrlSource": "derived"
}
  • version / gitSha / builtAt -- confirms the deployment actually shipped the build you expect, rather than an older cached one.
  • apiUrlSource / wsUrlSource -- "derived" means that URL was not set when the widget was built, so the widget is guessing it from the page's own host at runtime instead of using a fixed backend address. If the widget appears to be reaching the wrong backend, this is a common cause -- ask whoever deployed the widget to set the corresponding backend URL explicitly at build time.

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.