apache/echarts · error

Only one bmap component can exist

Error message

Only one bmap component can exist

What it means

Thrown inside the eachComponent loop in BMapCoordSys.create: each ECharts instance may own at most one bmap coordinate-system component. The loop assigns bmapCoordSys on the first matched bmap component and throws on a second match, so any duplicate bmap entry triggers the error on the second iteration. NOT guarded by __DEV__ — it throws in production.

Source

Thrown at extension-src/bmap/BMapCoordSys.ts:279

    Overlay.prototype.draw = function () {};

    return Overlay as BMapECExtendedOverlayCtor;
}

BMapCoordSys.create = function (ecModel, api) {
    let bmapCoordSys: BMapCoordSys;
    const root = api.getDom();

    // TODO Dispose
    ecModel.eachComponent(COMPONENT_MAIN_TYPE_BMAP, function (bmapModel: BMapModel) {
        const painter = api.getZr().painter;
        const viewportRoot = painter.getViewportRoot();
        if (typeof BMap === 'undefined') {
            throw new Error('BMap api is not loaded');
        }
        Overlay = Overlay || createOverlayCtor();
        if (bmapCoordSys) {
            throw new Error('Only one bmap component can exist');
        }
        let bmap;
        if (!bmapModel.__bmap) {
            // Not support IE8
            let bmapRoot: HTMLElement = root.querySelector('.ec-extension-bmap');
            if (bmapRoot) {
                // Reset viewport left and top, which will be changed
                // in moving handler in BMapView
                viewportRoot.style.left = '0px';
                viewportRoot.style.top = '0px';
                root.removeChild(bmapRoot);
            }
            bmapRoot = document.createElement('div');
            bmapRoot.className = 'ec-extension-bmap';
            // fix #13424
            bmapRoot.style.cssText = 'position:absolute;width:100%;height:100%';
            root.appendChild(bmapRoot);

View on GitHub (pinned to 30076aedcd)

Solutions

1. Keep exactly one bmap component per chart instance
2. If you need two maps, instantiate a second ECharts instance in a separate DOM container
3. When merging options, ensure the merged result has a single bmap key (use notMerge:true to replace)

Example fix

// before
chart.setOption({ bmap: {...} });
chart.setOption({ bmap: {...}, series: [...] }); // merge -> two bmap components

// after
chart.setOption({ bmap: {...}, series: [...] }, true); // notMerge replaces

const bmaps = Array.isArray(option.bmap) ? option.bmap : (option.bmap ? [option.bmap] : []);
if (bmaps.length > 1) {
  console.error('[bmap] only one bmap component allowed; trimming');
  option.bmap = bmaps[0];
}

When it happens

Trigger: An option object that resolves to more than one bmap component: e.g. merging two option objects that each declare a bmap key without notMerge, or passing an array with two bmap entries.

Common situations: Calling setOption a second time to add a bmap when one already exists (merge mode); copy-pasting bmap config into an existing bmap chart; composing base + overlay options that both carry bmap.

Related errors

• BMap api is not loaded
• Heatmap must use with visualMap
• levels[i].depth is mandatory and should be natural number
• Sankey is a DAG, the original data has cycle!
• Marker component is abstract component. Use markLine, markPo

AI-assisted analysis of apache/echarts@30076aedcd (2026-08-12). Data as JSON: /api/errors/833d4a409a9701ed. Report an issue: GitHub.