BMap api is not loaded

Error message

BMap api is not loaded

What it means

Thrown by the bmap (Baidu Map) extension's BMapCoordSys.create when the global BMap object is undefined at chart creation time. The bmap extension is a thin bridge that hands rendering off to the real Baidu Maps JS API, which must be loaded separately; without that API the coordinate system cannot construct the map. Unlike most ECharts assertions, this check is NOT guarded by __DEV__ and runs in production builds too.

Source

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

    };
    /**
     * @override
     */
    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';

View on GitHub (pinned to 30076aedcd)

Solutions

Load the Baidu Maps API script in <head> before initializing ECharts: <script src="https://api.map.baidu.com/api?v=3.0&ak=YOUR_AK"></script>
Initialize the bmap chart only after the BMap script's onload callback (or window.onload) fires
Verify the AK is valid and the runtime can reach api.map.baidu.com (check CSP / network)

Example fix

// before
chart.setOption({ bmap: {...}, series: [...] }); // throws: BMap api is not loaded

// after
// <script src="https://api.map.baidu.com/api?v=3.0&ak=YOUR_AK"></script>
window.onload = () => chart.setOption({ bmap: {...}, series: [...] });

Defensive patterns

Strategy: validation

Validate before calling

if (typeof (window as any).BMap === 'undefined') {
  console.error('[bmap] Baidu Maps API not loaded; aborting setOption');
  return;
}
chart.setOption(option);

Type guard

const isBmapLoaded = (): boolean => typeof (window as any).BMap !== 'undefined';

Prevention

Initialize the bmap chart only after the Baidu Maps script onload callback fires
Gate chart init behind an isBmapLoaded() check
Confirm Content-Security-Policy allows scripts from api.map.baidu.com

When it happens

Trigger: Calling setOption with a bmap component (or series referencing bmap) before the Baidu Maps JavaScript API <script> has finished loading. Also fires when the script tag is missing entirely, blocked by CSP, or loaded with an invalid/rejected AK (access key).

Common situations: Forgetting to add the Baidu Maps script tag; async/defer script not resolved before chart init; corporate network blocking api.map.baidu.com; AK key rejected or rate-limited; testing offline.

Related errors

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