addFrames: overwriting frame "${name}" with a frame whose na

Error message

addFrames: overwriting frame "${name}" with a frame whose name of type "number" also equates to "${name}". This is valid but may potentially lead to unexpected behavior since all plotly.js frame names are stored internally as strings.

What it means

Plotly.addFrames stores all frame names internally as strings. Adding a frame whose name is a JavaScript number that stringifies to an already-registered name (e.g. numeric 0 vs string '0') silently overwrites the existing frame. Plotly warns that this is valid but can cause unexpected behavior. The warning is throttled per call via numericNameWarningCount.

Source

Thrown at src/plot_api/plot_api.js:3460

        if (!Lib.isPlainObject(frameList[i])) continue;

        // The entire logic for checking for this type of name collision can be removed once we migrate to ES6 and
        // use a Map instead of an Object instance, as Map keys aren't converted to strings.
        var lookupName = frameList[i].name;
        var name = (_frameHash[lookupName] || _frameHashLocal[lookupName] || {}).name;
        var newName = frameList[i].name;
        var collisionPresent = _frameHash[name] || _frameHashLocal[name];

        if (
            name &&
            newName &&
            typeof newName === 'number' &&
            collisionPresent &&
            numericNameWarningCount < numericNameWarningCountLimit
        ) {
            numericNameWarningCount++;

            Lib.warn(
                'addFrames: overwriting frame "' +
                    (_frameHash[name] || _frameHashLocal[name]).name +
                    '" with a frame whose name of type "number" also equates to "' +
                    name +
                    '". This is valid but may potentially lead to unexpected ' +
                    'behavior since all plotly.js frame names are stored internally ' +
                    'as strings.'
            );

            if (numericNameWarningCount === numericNameWarningCountLimit) {
                Lib.warn(
                    'addFrames: This API call has yielded too many of these warnings. ' +
                        'For the rest of this call, further warnings about numeric frame ' +
                        'names will be suppressed.'
                );
            }
        }

View on GitHub (pinned to 1d090e0b5f)

Solutions

Coerce frame names to strings when creating frames (String(i) or template literals) so types match the internal string registry.
Use unique prefixed names (e.g. 'frame-0') to eliminate coercion collisions entirely.
If the overwrite is intentional, restructure the naming so it is explicit rather than an accident of coercion.

Example fix

// before
Plotly.addFrames(gd, frames.map((f, i) => ({name: i, data: f})));
// after
Plotly.addFrames(gd, frames.map((f, i) => ({name: String(i), data: f})));

Defensive patterns

Strategy: validation

Validate before calling

function assertStringFrameNames(frames) {
  const bad = frames.filter(f => typeof f.name === 'number');
  if (bad.length) {
    throw new TypeError('Frame names must be strings: ' + bad.map(f => f.name).join(', '));
  }
}
// usage: assertStringFrameNames(frames); Plotly.addFrames(gd, frames);

Type guard

function hasStringName(frame) {
  return frame != null && typeof frame.name === 'string' && frame.name.length > 0;
}

Prevention

Always construct frame names with String(i) or a prefix.
Never pass raw numeric indices as frame names.
Use unique descriptive names to avoid silent overwrites.
Audit frame sources (JSON vs code) for mixed name types.

When it happens

Trigger: Plotly.addFrames(gd, [{name: 0}, ...]) with typeof name === 'number' where String(name) collides with an existing frame name in _frameHash or _frameHashLocal, and fewer than numericNameWarningCountLimit such warnings have been emitted for this call.

Common situations: Generating frames in a loop with numeric indices as names while other code registered string names; mixing frame definitions from JSON (string names) with programmatic frames (number names); mapping dataset indices directly to frame names.

Related errors

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