plotly/plotly.js · warning

MathJax is not loaded. Math equations will not be rendered.

Error message

MathJax is not loaded. Math equations will not be rendered.

What it means

When plotly.js renders TeX math (text with $...$ and MathJax enabled in layout), it requires the MathJax library to be loaded in the page. If `window.MathJax` is absent, isMathJaxVersionSupported() warns once that equations will not be rendered and returns false, so the text is shown as raw TeX.

Source

Thrown at src/lib/svg_text_utils.js:225

var mathjaxSVGDocument = null;

// Function which returns the major version of MathJax as an integer,
// or null if MathJax is undefined or MathJax.version is falsy.
const mathJaxMajorVersion = () => (typeof MathJax !== 'undefined' && MathJax.version) ? parseInt(MathJax.version.split('.')[0]) : null;

// Only warn once per page about each of these conditions
var warnedMissingMathJax = false;
var warnedUnsupportedMathJax = false;

// plotly.js is only compatible with MathJax v3 and v4.
function isMathJaxVersionSupported() {
    const version = mathJaxMajorVersion();
    if(version === 3 || version === 4) return true;

    if(version === null) {
        if(!warnedMissingMathJax) {
            warnedMissingMathJax = true;
            Lib.warn('MathJax is not loaded. Math equations will not be rendered.');
        }
    } else if(!warnedUnsupportedMathJax) {
        warnedUnsupportedMathJax = true;
        Lib.warn('Unsupported MathJax version:', MathJax.version);
    }
    return false;
}

function texToSVG(_texString, _config, _callback) {
    const MathJaxVersion = mathJaxMajorVersion();

    var tmpDiv;

    const initiateMathJax = function() {
        if(!mathjaxSVGDocument) {
            const SVG = MathJax._.output.svg_ts.SVG;
            // fontCache 'local' keeps each rendered svg self-contained
            const svgConfig = Lib.extendFlat({}, MathJax.config.svg, {fontCache: 'local'});

View on GitHub (pinned to 1d090e0b5f)

Solutions

1. Include MathJax v3/v4 in the page before rendering: <script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js"></script>.
2. If loading asynchronously, wait for MathJax readiness (MathJax.startup.promise or the startup page-ready promise) before Plotly.newPlot.
3. Re-render / call Plotly.Plots.resize or re-plot once MathJax is available.
4. If math is not needed, remove $...$ markers or disable the math typesetting config to silence the warning.

Example fix

// before
Plotly.newPlot(gd, data); // MathJax not yet loaded
// after
await MathJax.startup.promise;
Plotly.newPlot(gd, data);

function ensureMathJax() {
  if (typeof window.MathJax === 'undefined') {
    const s = document.createElement('script');
    s.src = 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js';
    document.head.appendChild(s);
  }
}

function isMathJaxLoaded() { return typeof window !== 'undefined' && typeof window.MathJax !== 'undefined'; }

try {
  if (!isMathJaxLoaded()) await loadMathJax();
  Plotly.newPlot(gd, data);
} catch (e) {
  console.warn('Math unavailable, rendering plain text', e);
  Plotly.newPlot(gd, stripTeX(data));
}

When it happens

Trigger: Plotting text containing $...$ or \(...\) with layout.tex or MathJax config enabled while the MathJax script tag is missing, loads after plotly, or is loaded asynchronously after the first render.

Common situations: Forgetting the <script> tag for MathJax, loading MathJax with `defer`/`async` and calling Plotly.newPlot before it finishes, SPA routing removing the script, or CSP blocking the CDN.

Related errors

• Unsupported MathJax version:

AI-assisted analysis of plotly/plotly.js@1d090e0b5f (2026-09-02). Data as JSON: /api/errors/cfbf6bab32e157ae. Report an issue: GitHub.