{"record":{"id":"c32d91abd5627ab5","repo":"plotly/plotly.js","slug":"trying-to-add-layer-with-below-value-below-ref","errorCode":null,"errorMessage":"Trying to add layer with *below* value <below> referencing a layer that does not exist or that does not yet exist.","messagePattern":"Trying to add layer with \\*below\\* value <below> referencing a layer that does not exist or that does not yet exist\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/plots/map/map.js","lineNumber":786,"sourceCode":"// a layer that exist and then add the layer to the map,\nproto.addLayer = function (opts, below) {\n    var map = this.map;\n\n    if (typeof below === 'string') {\n        if (below === '') {\n            map.addLayer(opts, below);\n            return;\n        }\n\n        var mapLayers = this.getMapLayers();\n        for (var i = 0; i < mapLayers.length; i++) {\n            if (below === mapLayers[i].id) {\n                map.addLayer(opts, below);\n                return;\n            }\n        }\n\n        Lib.warn(\n            [\n                'Trying to add layer with *below* value',\n                below,\n                'referencing a layer that does not exist',\n                'or that does not yet exist.'\n            ].join(' ')\n        );\n    }\n\n    map.addLayer(opts);\n};\n\n// convenience method to project a [lon, lat] array to pixel coords\nproto.project = function ([lon, lat]) {\n    return this.map.project(new maplibregl.LngLat(lon, lat));\n};\n\n// get map's current view values in plotly.js notation","sourceCodeStart":768,"sourceCodeEnd":804,"githubUrl":"https://github.com/plotly/plotly.js/blob/1d090e0b5ffb8d0fdf6e0e4ff51d3f3cf67f1314/src/plots/map/map.js#L768-L804","documentation":"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.","triggerScenarios":"Thrown at src/plots/map/map.js:786 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["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.","Use below: '' when you want the trace above everything, or check the style's layer list before choosing a value.","Ensure the layer referenced (e.g. added via layout.map.layers) is added before traces that use it as below.","Note the message can read 'does not yet exist' for ordering; add the referenced layer first."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"1d090e0b5ffb8d0fdf6e0e4ff51d3f3cf67f1314","analyzedAt":"2026-09-02T22:03:39.906Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-10T02:17:09.455Z"}