."}}]}]}

plotly/plotly.js · warning

Unsupported MathJax version:

Error message

Unsupported MathJax version:

What it means

plotly.js supports MathJax major versions 3 and 4 for rendering TeX to SVG. If MathJax is loaded but its version is neither (e.g. the legacy 2.x), isMathJaxVersionSupported() warns once with 'Unsupported MathJax version:' plus MathJax.version and returns false, leaving equations unrendered.

Source

Thrown at src/lib/svg_text_utils.js:229

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'});
            // MathJax v4 enables automatic inline linebreaking by default, which
            // messes up our layout assumptions. Disabling it gives behavior consistent with v3.
            if(MathJaxVersion === 4) {
                svgConfig.linebreaks = Lib.extendFlat({}, svgConfig.linebreaks, {inline: false});

View on GitHub (pinned to 1d090e0b5f)

Solutions

  1. Upgrade to MathJax 3 or 4: <script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js"></script>.
  2. Remove any legacy MathJax 2.x script tags and their config objects (MathJax.Hub.Config).
  3. Port v2 configuration to the v3/v4 window.MathJax = {...} config format.
  4. Re-render the plot after the supported MathJax version loads.

Example fix

<!-- before -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.9/MathJax.js"></script>
<!-- after -->
<script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js"></script>
Defensive patterns

Strategy: validation

Validate before calling

function mathJaxMajorOk() {
  const v = window.MathJax && window.MathJax.version;
  const major = v && parseInt(v, 10);
  return major === 3 || major === 4;
}

Type guard

function isSupportedMathJax(m) { return m != null && [3, 4].includes(parseInt(m.version, 10)); }

Try / catch

try {
  if (!mathJaxMajorOk()) throw new Error('MathJax 3/4 required');
  Plotly.newPlot(gd, data);
} catch (e) {
  console.warn(e.message);
  Plotly.newPlot(gd, data); // plain text fallback
}

Prevention

When it happens

Trigger: Page loads MathJax 2.x (e.g. mathjax@2/latest or MathJax.js from the legacy CDN) while plotly.js text contains TeX, or a MathJax beta/other build whose version string does not parse to 3 or 4.

Common situations: Upgrading or downgrading MathJax independently of plotly, following older tutorials that reference MathJax 2.x CDN URLs, or vendored MathJax builds pinned to v2.

Related errors

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