apache/echarts · error

matrix coordinate system should be specified.

Error message

matrix coordinate system should be specified.

What it means

Thrown by the `matrix` coordinate-system resolver in referHelper.ts:215 when a series is bound to the `matrix` coordinate system but no `matrix` component model can be resolved. The resolver calls `seriesModel.getReferringComponents('matrix', SINGLE_REFERRING).models[0]`; SINGLE_REFERRING expects exactly one match by `matrixIndex`/`matrixId` (or the first as default). If that returns undefined, the option is missing a top-level `matrix` component (or its registration), so the chart has no coordinate container to derive its `x`/`y` dimensions from. The throw is guarded by `__DEV__`, so in a production/minified build it is skipped and execution falls through to `matrixModel.getDimensionModel('x')`, which fails as a null dereference instead.

Source

Thrown at src/model/referHelper.ts:222

            axisMap.set(axisDim, axisModel);

            if (isCategory(axisModel)) {
                categoryAxisMap.set(axisDim, axisModel);
                if (result.firstCategoryDimIndex == null) {
                    result.firstCategoryDimIndex = index;
                }
            }
        });
    },

    matrix: function (seriesModel, result, axisMap, categoryAxisMap) {
        const matrixModel = seriesModel.getReferringComponents(
            'matrix', SINGLE_REFERRING
        ).models[0] as MatrixModel;

        if (__DEV__) {
            if (!matrixModel) {
                throw new Error('matrix coordinate system should be specified.');
            }
        }

        result.coordSysDims = ['x', 'y'];
        const xModel = matrixModel.getDimensionModel('x');
        const yModel = matrixModel.getDimensionModel('y');
        axisMap.set('x', xModel);
        axisMap.set('y', yModel);
        categoryAxisMap.set('x', xModel);
        categoryAxisMap.set('y', yModel);
    },
};

function isCategory(axisModel: AxisBaseModel) {
    return axisModel.get('type') === 'category';
}

View on GitHub (pinned to 30076aedcd)

Solutions

1. If using on-demand imports, register the matrix component before setOption: `import { MatrixComponent } from 'echarts/components'; echarts.use([MatrixComponent]);`
2. Add a top-level `matrix` option array that defines the x/y dimensions the series references, e.g. `matrix: [{ x: {...}, y: {...} }]`.
3. Verify `matrixIndex`/`matrixId` on the series matches an existing matrix component (or omit them to use the first matrix as default).
4. If `matrix` was set unintentionally, remove `coordinateSystem: 'matrix'` from the series or switch to a coordinate system you have actually configured (cartesian2d, geo, calendar, etc.).

Example fix

// before
import * as echarts from 'echarts/core';
import { HeatmapChart } from 'echarts/charts';
echarts.use([HeatmapChart]);
const option = {
  series: [{ type: 'heatmap', coordinateSystem: 'matrix', data: [...] }]
  // no matrix component defined or registered
};

// after
import * as echarts from 'echarts/core';
import { HeatmapChart } from 'echarts/charts';
import { MatrixComponent } from 'echarts/components';
echarts.use([HeatmapChart, MatrixComponent]);
const option = {
  matrix: [{ /* x/y layout config */ }],
  series: [{ type: 'heatmap', coordinateSystem: 'matrix', data: [...] }]
};

// Before chart.setOption, assert every series bound to 'matrix' has a matrix component
// and that MatrixComponent is registered (on-demand builds).
function assertMatrixReady(option, echartsRef) {
  const seriesArr = [].concat(option.series || []);
  const usesMatrix = seriesArr.some(s => s && s.coordinateSystem === 'matrix');
  if (!usesMatrix) return;
  if (!option.matrix || !option.matrix.length) {
    throw new Error('Option uses coordinateSystem:"matrix" but defines no `matrix` component.');
  }
  // crude registration check: MatrixComponent registers a 'matrix' coordinate system
  const inst = echartsRef.init(null, null, { ssr: true, width: 1, height: 1 });
  try { inst.setOption({ matrix: [{}] }); } finally { inst.dispose(); }
}

// Narrow an option to the matrix-capable shape before relying on it.
function isMatrixOption(option) {
  return Array.isArray(option.matrix) && option.matrix.length > 0
    && Array.isArray(option.series)
    && option.series.some(s => s && s.coordinateSystem === 'matrix');
}

When it happens

Trigger: A series whose effective coordinate system is `matrix` (e.g. `series: [{ type: 'heatmap' | 'scatter' | 'treemap' | 'tree' | 'sankey' | 'custom', coordinateSystem: 'matrix' }]`, or a `grid`/`pie`/`map`/`graph` option that resolves to matrix) runs while (a) no `matrix: [...]` block exists in the option, or (b) the `MatrixComponent` module was never registered with `echarts.use([...])` in an on-demand build, or (c) `matrixIndex`/`matrixId` on the series does not match any defined matrix component.

Common situations: Switching from the full `echarts` bundle to tree-shaken `echarts/core` and forgetting `MatrixComponent` in the `.use()` list; defining a heatmap/scatter with `coordinateSystem: 'matrix'` but omitting the companion `matrix` option array; setting `matrixIndex`/`matrixId` to a value with no matching matrix component; upgrading an ECharts version where matrix support or its install path changed.

Related errors

• {mainType}.type should be specified.
• Component {mainType}.{subType} is used but not imported.
• Only one bmap component can exist
• Heatmap must use with visualMap
• Line not support coordinateSystem besides cartesian and pola

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