plotly/plotly.js · error

animate failure: frame not found: "${frameName}"

Error message

animate failure: frame not found: "${frameName}"

What it means

Plotly.animate was asked to animate a frame by name that does not exist in the graph's frame registry (_frameHash). The animate call validates every requested 'byname' frame up front and rejects the returned promise without animating if any is missing. Frames must be registered via Plotly.addFrames (or passed inline) before they can be animated by name.

Source

Thrown at src/plot_api/plot_api.js:3338

                    frameList.push({
                        type: 'byname',
                        name: frameOrName,
                        data: setTransitionConfig({ name: frameOrName })
                    });
                } else if (Lib.isPlainObject(frameOrName)) {
                    frameList.push({
                        type: 'object',
                        data: setTransitionConfig(Lib.extendFlat({}, frameOrName))
                    });
                }
            }
        }

        // Verify that all of these frames actually exist; return and reject if not:
        for (i = 0; i < frameList.length; i++) {
            frame = frameList[i];
            if (frame.type === 'byname' && !trans._frameHash[frame.data.name]) {
                Lib.warn('animate failure: frame not found: "' + frame.data.name + '"');
                reject();
                return;
            }
        }

        // If the mode is either next or immediate, then all currently queued frames must
        // be dumped and the corresponding .animate promises rejected.
        if (['next', 'immediate'].indexOf(animationOpts.mode) !== -1) {
            discardExistingFrames();
        }

        if (animationOpts.direction === 'reverse') {
            frameList.reverse();
        }

        var currentFrame = gd._fullLayout._currentFrame;
        if (currentFrame && animationOpts.fromcurrent) {
            var idx = -1;

View on GitHub (pinned to 1d090e0b5f)

Solutions

1. Register the frame before animating: await Plotly.addFrames(gd, [{name: 'myFrame', data: {...}}]) then call Plotly.animate.
2. Attach a .catch to the animate promise so the rejection is handled gracefully.
3. Confirm the frames were added to the same graph div being animated; re-add frames after any newPlot/react call.
4. Inspect the registered frame names (gd._transitionData._frameHash) to verify the exact name string.

Example fix

// before
Plotly.animate(gd, 'frame2', {transition: {duration: 500}});
// after
Plotly.addFrames(gd, [{name: 'frame2', data: [{x: [1,2,3], y: [2,4,6]}]}])
  .then(() => Plotly.animate(gd, 'frame2', {transition: {duration: 500}}))
  .catch(err => console.warn('animation skipped:', err));

function frameExists(gd, name) {
  const hash = (gd._transitionData && gd._transitionData._frameHash) || {};
  return Object.prototype.hasOwnProperty.call(hash, String(name));
}
// usage: if (frameExists(gd, 'frame2')) Plotly.animate(gd, 'frame2', opts);

function isRegisteredFrameName(name, gd) {
  return typeof name === 'string' &&
    !!gd._transitionData &&
    !!gd._transitionData._frameHash[name];
}

Plotly.animate(gd, frameName, opts)
  .then(function () { /* animation complete */ })
  .catch(function (err) {
    console.warn('Animation skipped, frame missing:', frameName, err);
  });

When it happens

Trigger: Plotly.animate(gd, 'myFrame', ...) where 'myFrame' was never added via Plotly.addFrames; referencing a frame after Plotly.newPlot/Plotly.react recreated the graph div (frames are per-div state); typo or case mismatch in the frame name; number-vs-string name coercion making the lookup miss.

Common situations: Tutorials where frame names were never registered; SPA route changes recreating the plot while animating frames from the previous div; frames added to a different graph div; numeric frame names colliding with string keys.

Related errors

• API call to Plotly.${method} rejected.
• unrecognized GUI edit: ${key}
• unrecognized GUI edit: ${key} in trace uid ${uid}
• addFrames: overwriting frame "${name}" with a frame whose na
• addFrames: This API call has yielded too many of these warni

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