plotly/plotly.js · error

Trying to add layer with *below* value <below> referencing a

Error message

Trying to add layer with *below* value <below> referencing a layer that does not exist or that does not yet exist.

What it means

Diagnostic warning (Lib.warn) in the map (mapbox-style) subplot's addLayer. When adding a trace layer with a 'below' option, the code scans existing map layer ids; if no layer matches the given 'below' id, the layer cannot be inserted beneath it. This usually means the referenced base layer (e.g. a style layer like 'water' or a land layer) does not exist in the current map style or has not been added yet. Rendering continues with the layer added on top instead of below.

Source

Thrown at src/plots/map/map.js:786

// a layer that exist and then add the layer to the map,
proto.addLayer = function (opts, below) {
    var map = this.map;

    if (typeof below === 'string') {
        if (below === '') {
            map.addLayer(opts, below);
            return;
        }

        var mapLayers = this.getMapLayers();
        for (var i = 0; i < mapLayers.length; i++) {
            if (below === mapLayers[i].id) {
                map.addLayer(opts, below);
                return;
            }
        }

        Lib.warn(
            [
                'Trying to add layer with *below* value',
                below,
                'referencing a layer that does not exist',
                'or that does not yet exist.'
            ].join(' ')
        );
    }

    map.addLayer(opts);
};

// convenience method to project a [lon, lat] array to pixel coords
proto.project = function ([lon, lat]) {
    return this.map.project(new maplibregl.LngLat(lon, lat));
};

// get map's current view values in plotly.js notation

View on GitHub (pinned to 1d090e0b5f)

Solutions

1. Set trace.below to a layer id that exists in the active map style (inspect via map.getStyle().layers), or use '' to place the layer on top.
2. Use below: '' when you want the trace above everything, or check the style's layer list before choosing a value.
3. Ensure the layer referenced (e.g. added via layout.map.layers) is added before traces that use it as below.
4. Note the message can read 'does not yet exist' for ordering; add the referenced layer first.

When it happens

Trigger: Thrown at src/plots/map/map.js:786 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/c32d91abd5627ab5. Report an issue: GitHub.