apache/echarts · error

Heatmap must use with visualMap

Error message

Heatmap must use with visualMap

What it means

DEV-only guard in HeatmapView.render: a heatmap series encodes value->color exclusively through a visualMap component. The render walks ecModel's visualMap components and checks whether any targets this series; if none does, it throws. Without a visualMap the heatmap has no color mapping, so dev builds refuse to render. Stripped in production (cells would render without color encoding).

Source

Thrown at src/chart/heatmap/HeatmapView.ts:114

    readonly type = HeatmapView.type;

    private _hmLayer: HeatmapLayer;

    private _progressiveEls: Element[];

    render(seriesModel: HeatmapSeriesModel, ecModel: GlobalModel, api: ExtensionAPI) {
        let visualMapOfThisSeries;
        ecModel.eachComponent('visualMap', function (visualMap: VisualMapModel) {
            visualMap.eachTargetSeries(function (targetSeries) {
                if (targetSeries === seriesModel) {
                    visualMapOfThisSeries = visualMap;
                }
            });
        });

        if (__DEV__) {
            if (!visualMapOfThisSeries) {
                throw new Error('Heatmap must use with visualMap');
            }
        }

        // Clear previously rendered progressive elements.
        this._progressiveEls = null;

        this.group.removeAll();

        const coordSys = seriesModel.coordinateSystem;
        if (coordSys.type === 'cartesian2d'
            || coordSys.type === 'calendar'
            || coordSys.type === 'matrix'
        ) {
            this._renderOnGridLike(seriesModel, api, 0, seriesModel.getData().count());
        }
        else if (isGeoLikeCoordSys(coordSys)) {
            this._renderOnGeo(
                coordSys, seriesModel, visualMapOfThisSeries, api

View on GitHub (pinned to 30076aedcd)

Solutions

1. Add a visualMap component (continuous or piecewise) whose range covers the heatmap data values
2. Ensure the visualMap targets the heatmap (by default it targets all series; otherwise set seriesIndex)
3. If a single fill color suffices, consider a different chart type (e.g. bar)

Example fix

// before
chart.setOption({ series: [{ type: 'heatmap', data: [...] }] });

// after
chart.setOption({
  tooltip: {},
  visualMap: { min: 0, max: 10, calculable: true, orient: 'horizontal' },
  series: [{ type: 'heatmap', data: [...] }]
});

const series = option.series || [];
const hasHeatmap = series.some((s: any) => s.type === 'heatmap');
const hasVisualMap = !!option.visualMap;
if (hasHeatmap && !hasVisualMap) {
  console.error('[heatmap] a visualMap component is required');
}

When it happens

Trigger: Declaring a series of type 'heatmap' with no visualMap component in the option, or with a visualMap whose target series index/id does not include this heatmap.

Common situations: Removing visualMap while debugging; copying a heatmap snippet but dropping the visualMap block; seriesIndex/seriesId mismatch on the visualMap.

Related errors

• Heatmap on cartesian must have two category axes
• Heatmap on cartesian must have two axes with boundaryGap tru
• levels[i].depth is mandatory and should be natural number
• Marker component is abstract component. Use markLine, markPo
• xAxis and yAxis must use the same grid

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