plotly/plotly.js · error

Trace <traceOut.index> must match within bingroup <groupName

Error message

Trace <traceOut.index> must match within bingroup <groupName>. Ignoring its bingroup: <bingroupIn> setting.

What it means

Warning from the histogram cross-trace binning pass. When traces are auto-grouped (via autobinning or shared bingroup), the resolved groupName is compared with each trace's explicit layout.bingroup setting; if a trace's declared bingroup differs from the group it actually landed in (because its auto-detected bin options matched another group), the declared bingroup is ignored so binning stays consistent, and this warning tells the user their bingroup setting was overridden.

Source

Thrown at src/traces/histogram/cross_trace_defaults.js:188

        // trace is detected as "must match"
        if(traces.length === 1) {
            otherTracesList.push(traces[0]);
            continue;
        }

        var binGroupFound = false;
        if(traces.length) {
            traceOut = traces[0];
            binGroupFound = coerce('bingroup');
        }

        groupName = binGroupFound || groupName;

        for(i = 0; i < traces.length; i++) {
            traceOut = traces[i];
            var bingroupIn = traceOut._input.bingroup;
            if(bingroupIn && bingroupIn !== groupName) {
                Lib.warn([
                    'Trace', traceOut.index, 'must match',
                    'within bingroup', groupName + '.',
                    'Ignoring its bingroup:', bingroupIn, 'setting.'
                ].join(' '));
            }
            traceOut.bingroup = groupName;

            // N.B. no need to worry about 2dMap case
            // (where both bin direction are set in each trace)
            // as 2dMap trace never "have to match"
            fillBinOpts(traceOut, groupName, orientation2binDir(traceOut));
        }
    }

    // setup binOpts for traces that can but don't have to match,
    // notice that these traces can be matched with traces that have to match
    for(i = 0; i < otherTracesList.length; i++) {
        traceOut = otherTracesList[i];

View on GitHub (pinned to 1d090e0b5f)

Solutions

1. Set layout.bingroup consistently across all traces you want binned together (or omit it entirely).
2. Ensure traces in the intended group have compatible axis types and calendars so auto-grouping agrees with the declared bingroup.
3. Use matching xbins/ybins settings if you need manual control without bingroup.
4. Silence by aligning the trace's auto bin group with its declared bingroup name.

When it happens

Trigger: Thrown at src/traces/histogram/cross_trace_defaults.js:188 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/f42bf41e61e74b52. Report an issue: GitHub.