Skip to content
English - United Kingdom
Sign in
Contact us
  • There are no suggestions because the search field is empty.

How to Troubleshoot NINA Chatbot Errors on the Surgery Website

Purpose of Document

When NINA produces an error on the surgery website, patients cannot access the chatbot and the surgery loses the self-service benefit NINA provides. Errors can range from NINA not appearing at all, to appearing but not functioning correctly, to displaying error messages or blank screens. Support staff must be able to work through a systematic troubleshooting process and involve the website developer or engineering team at the right point.

Background: How NINA Is Installed

NINA is installed on the surgery's website via a single script tag. The script is configured with surgery-specific credentials and must be placed correctly within the website's code for NINA to load and function.

The script contains the following parameters, all of which are provided by QuantumLoop AI during the deployment process:

Parameter Purpose
src The source URL for the NINA widget script
data-widget-id Unique identifier for this surgery's NINA widget
data-surgery-number The surgery's phone number for NINA to reference
data-surgery-name The surgery's name displayed within the chatbot
data-auth-token Authentication token for secure communication
data-signature Security signature for request verification

All placeholder values are provided to the surgery's website developer by QuantumLoop AI via email. The developer should never attempt to generate these values themselves.

Platform-Specific Installation Requirements

Different website platforms require slightly different approaches. Support staff must confirm the platform before troubleshooting.

Plain HTML websites

The script must be placed inside the <head> tag of the main HTML file. It must load on every page where NINA should appear.

HubSpot websites

The script is added via Settings, then Website, then Pages, then Templates. The developer opens the Global Header HTML or relevant template and pastes the NINA script directly into the Header HTML section.

Important: HubSpot automatically includes <head> and <body> tags. The developer must not add these tags again. Only the script tag itself is required.

React applications

For React, the script is placed inside the <Head> component within the _document.js or document.tsx file. It must sit in the Head section so it loads globally across all pages.

Next.js applications

For Next.js, the script is placed inside the <Head> tag within the custom Document component. The standard placement is inside the <Html> and <Head> components in the Document file. The <body> tag must not contain the NINA script.

If the NINA script is in the <body> instead of <head> on a Next.js site, NINA may fail to load consistently.

Common Errors and How to Troubleshoot Them

1. NINA widget is not appearing on the website at all

This is the most common report. See Article 29 (NINA is Not Appearing on the Surgery Website After Installation) for full guidance on this specific scenario.

In brief, the most common causes are:

  • The script has not been added to the website yet
  • The script was added to the wrong location
  • The script parameters contain incorrect values
  • NINA is currently disabled for that surgery

2. NINA appears but displays a blank or empty chat window

This typically indicates the widget has loaded but cannot connect to the NINA backend, or the surgery's configuration has not been completed.

What to do:

  • Confirm with the QuantumLoop team that NINA configuration has been completed and the surgery is fully set up on the backend
  • Check whether the deployment code sent to the developer matches the most recently issued credentials. Outdated credentials will prevent connection.
  • Ask the developer to open the browser developer console (F12 in most browsers) and check for any error messages related to the NINA script. Look for failed network requests, authentication errors, or CORS errors.
  • If no configuration issue is found, escalate to engineering with the surgery ODS code and a description of what the blank window shows

3. NINA loads but immediately shows an error message to the patient

Error messages visible to patients suggest a backend communication issue, an authentication failure, or a session problem.

What to do:

  • Ask the practice or a team member to screenshot the error message exactly as it appears
  • Check whether the error appeared after a recent website update or change to the surgery's website code
  • Check whether the script credentials (auth token, signature, widget ID) are still current and have not been changed
  • Check the browser console for specific error codes
  • If the error message includes raw system data or unformatted output, escalate to engineering immediately as this is a presentation layer issue

4. NINA works on some pages but not others

This indicates the script is loaded conditionally rather than globally.

What to do:

  • Confirm with the website developer that the script is installed in the global header or layout file, not on individual pages
  • For HubSpot, confirm the script is in the Global Header HTML template, not a page-specific template
  • For React and Next.js, confirm the script is in the Document component, not in individual page components
  • Ask the developer to verify the script loads on every page by checking the page source on affected pages

5. NINA displays correctly on desktop but not on mobile

This may indicate a responsive layout issue with the surgery's website rather than a NINA fault.

What to do:

  • Confirm whether the script is loading on mobile by checking the mobile browser console
  • Check whether the surgery's website has a separate mobile template or theme that does not include the global header where the NINA script is installed
  • If the script is present in the mobile page source but NINA is not displaying, escalate to engineering with device and browser details

6. NINA was working and has suddenly stopped

Sudden failures after a period of working correctly usually indicate one of the following:

  • The surgery's website has been updated and the script has been removed or overwritten
  • The website developer has changed the site template or CMS and the global header no longer contains the NINA script
  • The surgery has changed their website provider and NINA has not been reinstalled on the new site

What to do:

  • Ask the practice when NINA last worked and whether any website changes have been made since
  • Ask the developer to check whether the NINA script is still present in the global header
  • If the script has been removed, resend the deployment code email and request reinstallation
  • If the surgery has moved to a new website provider, contact QuantumLoop support to arrange a new deployment

7. Browser console shows a CORS error or blocked request

CORS (Cross-Origin Resource Sharing) errors indicate the browser is blocking NINA's requests because the surgery's website domain is not authorised on the QuantumLoop backend.

What to do:

  • Note the exact domain the surgery's website is on, including any subdomains
  • Escalate to engineering with the domain name and ODS code so the domain can be whitelisted

8. NINA is loading but responses are slow or timing out

Slow responses or timeouts may indicate a network issue on the patient's end, a browser extension blocking the request, or a QuantumLoop backend issue.

What to do:

  • Ask the practice to confirm whether the issue is affecting all patients or specific users
  • Ask a team member to test NINA in an incognito browser window with no extensions active
  • Check internal monitoring channels for any active platform degradation alerts
  • If the issue is widespread and no browser extension is the cause, escalate to engineering

Quick Verification Checklist

Use this checklist when a practice reports a NINA error. Work through it in order before escalating.

  1. Is the NINA script present in the website's global header or head tag? (Ask the developer to check the page source)
  2. Are the script parameters correct and current? (widget-id, auth-token, signature, surgery-number, surgery-name)
  3. Is the script placed in the correct location for the platform (head tag for HTML and Next.js, global header for HubSpot, Document component for React)?
  4. Has the surgery's website been updated recently? Could the script have been overwritten?
  5. Is NINA enabled in the QuantumLoop configuration? (Check internally)
  6. Is there a CORS error, authentication error, or network error in the browser console?
  7. Does NINA load on an incognito window with no browser extensions active?

If all the above checks pass and NINA is still not working, escalate to engineering.

How to Check the Browser Console for NINA Errors

The browser console provides the most useful diagnostic information for NINA errors. Support staff should guide website developers through this process.

Steps to open the browser console:

  1. Open the surgery's website in a desktop browser
  2. Press F12 (Windows) or Command + Option + I (Mac) to open developer tools
  3. Click the Console tab
  4. Reload the page
  5. Look for any red error messages related to the NINA script, failed network requests, or authentication failures

Common error patterns to look for:

  • Failed to load resource: indicates the script src URL is not accessible or incorrect
  • 401 Unauthorized: indicates an authentication token or signature issue
  • CORS policy blocked: indicates a domain not whitelisted on the QuantumLoop backend
  • Uncaught TypeError: may indicate a script conflict with another element on the page

Capture the exact error text and include it when escalating to engineering.

Step-by-Step Triage Process

  1. Confirm the surgery's website platform: HTML, HubSpot, React, Next.js, or other.
  2. Ask the developer to confirm the NINA script is present in the correct location for that platform.
  3. Confirm whether NINA configuration has been completed on the QuantumLoop backend.
  4. Ask the developer to check the browser console for errors and share the output.
  5. Work through the verification checklist above.
  6. If all checks pass and the error persists, escalate to engineering with all relevant information.

What to Tell the Practice

Example wording when the script has not been installed correctly:

"It looks like the NINA script may not have been placed in the correct location on your website. Could you ask your website developer to check that the script is in the global header of the site rather than on an individual page? We have also resent the installation instructions to help guide them through the process."

Example wording when the issue is unresolved after basic checks:

"We have worked through the standard checks with your developer and cannot identify the cause from our side. We are now escalating this to our engineering team who will investigate directly. We will come back to you with an update as soon as possible."

Common Mistakes

  • Asking the practice to reinstall NINA before first checking whether the script is present in the correct location
  • Not checking whether NINA has been disabled in the QuantumLoop configuration before investigating a script issue
  • Not confirming the platform before advising on script placement. Placement differs between HTML, HubSpot, React and Next.js.
  • Not asking the developer to check the browser console before escalating
  • Forgetting that a website update or migration can remove the NINA script without anyone noticing

Escalation Guidance

Escalate to engineering if:

  • All basic checks pass and NINA is still not loading or functioning
  • A CORS error is present and the domain needs to be whitelisted
  • Raw system data or unformatted output is visible in the NINA interface
  • A blank chat window persists after confirming configuration is complete
  • The issue affects multiple surgeries simultaneously

When escalating, always include:

  • Surgery name and ODS code
  • Website platform used
  • Whether the script is confirmed present in the correct location
  • Browser console error messages (exact text)
  • Whether the issue appeared suddenly after a website change
  • Whether the issue affects all patients or specific users or devices

Last Reviewed: May 2026 Owner: Support and Customer Success