Warning: addFrames accepts frames with numeric names, but th

Error message

Warning: addFrames accepts frames with numeric names, but the numbers areimplicitly cast to strings

What it means

Plotly.addFrames() emits this warning when a frame's `name` is a number. Frame names are used as string keys for frame lookup and ordering, so numeric names are implicitly cast to strings (e.g. 1 becomes "1"), which can surprise users comparing names. It is a heads-up about silent type coercion, not a failure.

Source

Thrown at src/plot_api/plot_api.js:3502

        });
    }

    // Sort this, taking note that undefined insertions end up at the end:
    insertions.sort(function (a, b) {
        if (a.index > b.index) return -1;
        if (a.index < b.index) return 1;
        return 0;
    });

    var ops = [];
    var revops = [];
    var frameCount = _frames.length;

    for (i = insertions.length - 1; i >= 0; i--) {
        frame = insertions[i].frame;

        if (typeof frame.name === 'number') {
            Lib.warn(
                'Warning: addFrames accepts frames with numeric names, but the numbers are' +
                    'implicitly cast to strings'
            );
        }

        if (!frame.name) {
            // Repeatedly assign a default name, incrementing the counter each time until
            // we get a name that's not in the hashed lookup table:
            while (_frameHash[(frame.name = 'frame ' + gd._transitionData._counter++)]);
        }

        if (_frameHash[frame.name]) {
            // If frame is present, overwrite its definition:
            for (j = 0; j < _frames.length; j++) {
                if ((_frames[j] || {}).name === frame.name) break;
            }
            ops.push({ type: 'replace', index: j, value: frame });
            revops.unshift({ type: 'replace', index: j, value: _frames[j] });

View on GitHub (pinned to 1d090e0b5f)

Solutions

Convert frame names to strings before calling addFrames: name: String(1) or name: '1'.
If ordering matters, zero-pad string names (e.g. '001') since frame ordering/name comparison is lexicographic on strings.
If the number is only a label, keep it numeric but accept the warning; behavior is unchanged apart from the cast.

Example fix

// before
Plotly.addFrames(gd, [{name: 1, data: [{x: [1], y: [1]}]}]);
// after
Plotly.addFrames(gd, [{name: '1', data: [{x: [1], y: [1]}]}]);

Defensive patterns

Strategy: validation

Validate before calling

function validateFrameNames(frames) {
  frames.forEach((f, i) => {
    if (typeof f.name === 'number') throw new TypeError(`frames[${i}].name must be a string, got number ${f.name}`);
  });
}
// run before: validateFrameNames(myFrames); Plotly.addFrames(gd, myFrames);

Type guard

function isStringFrameName(f) { return typeof f.name === 'string'; }
const safe = frames.filter(isStringFrameName);

Prevention

Always build frame names with String(i) when deriving them from numbers.
Zero-pad numeric names if lexicographic ordering matters.
Lint JSON frame definitions for unquoted numeric names.
Document frame names as string keys in your data pipeline.

When it happens

Trigger: Calling Plotly.addFrames(gd, [{name: 1, data: {...}}, ...]) or passing frame objects built from numeric IDs, JSON data where names were not quoted, or generated frames whose names come from loop counters.

Common situations: Programmatically generating frames from numeric sequence numbers or database IDs; loading frames from JSON where names were numeric; migrating code that relied on numeric ordering by name.

Related errors

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