plotly/plotly.js · error · Error

computeFrame must be given a string frame name

Error message

computeFrame must be given a string frame name

What it means

Argument guard in plots.computeFrame, which merges a named keyframe from gd._transitionData._frameHash for animations. The frame name is used as a lookup key (and eventually .toString()'d), so null/undefined would crash downstream and objects would silently look up wrong keys. The throw fires when frameName is not a string (or number); note the code deliberately tolerates numbers since they stringify cleanly, but other types are rejected.

Source

Thrown at src/plots/plots.js:2081

 * @param {object} frameLookup
 *      An object containing frames keyed by name (i.e. gd._transitionData._frameHash)
 * @param {string} frame
 *      The name of the keyframe to be computed
 *
 * Returns: a new object with the merged content
 */
plots.computeFrame = function(gd, frameName) {
    var frameLookup = gd._transitionData._frameHash;
    var i, traceIndices, traceIndex, destIndex;

    // Null or undefined will fail on .toString(). We'll allow numbers since we
    // make it clear frames must be given string names, but we'll allow numbers
    // here since they're otherwise fine for looking up frames as long as they're
    // properly cast to strings. We really just want to ensure here that this
    // 1) doesn't fail, and
    // 2) doens't give an incorrect answer (which String(frameName) would)
    if(!frameName) {
        throw new Error('computeFrame must be given a string frame name');
    }

    var framePtr = frameLookup[frameName.toString()];

    // Return false if the name is invalid:
    if(!framePtr) {
        return false;
    }

    var frameStack = [framePtr];
    var frameNameStack = [framePtr.name];

    // Follow frame pointers:
    while(framePtr.baseframe && (framePtr = frameLookup[framePtr.baseframe.toString()])) {
        // Avoid infinite loops:
        if(frameNameStack.indexOf(framePtr.name) !== -1) break;

        frameStack.push(framePtr);

View on GitHub (pinned to 1d090e0b5f)

Solutions

1. Pass the frame name as a string, e.g. Plotly.animate(gd, 'frameName', ...).
2. Coerce with String(frameName) before calling, if the value originates from user input.
3. Check that the frame was registered via Plotly.addFrames with a string 'name'.

When it happens

Trigger: Thrown at src/plots/plots.js:2081 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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