{"record":{"id":"d0582b4a36122349","repo":"apache/echarts","slug":"matrix-coordinate-system-should-be-specified","errorCode":null,"errorMessage":"matrix coordinate system should be specified.","messagePattern":"matrix coordinate system should be specified\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/model/referHelper.ts","lineNumber":222,"sourceCode":"            axisMap.set(axisDim, axisModel);\n\n            if (isCategory(axisModel)) {\n                categoryAxisMap.set(axisDim, axisModel);\n                if (result.firstCategoryDimIndex == null) {\n                    result.firstCategoryDimIndex = index;\n                }\n            }\n        });\n    },\n\n    matrix: function (seriesModel, result, axisMap, categoryAxisMap) {\n        const matrixModel = seriesModel.getReferringComponents(\n            'matrix', SINGLE_REFERRING\n        ).models[0] as MatrixModel;\n\n        if (__DEV__) {\n            if (!matrixModel) {\n                throw new Error('matrix coordinate system should be specified.');\n            }\n        }\n\n        result.coordSysDims = ['x', 'y'];\n        const xModel = matrixModel.getDimensionModel('x');\n        const yModel = matrixModel.getDimensionModel('y');\n        axisMap.set('x', xModel);\n        axisMap.set('y', yModel);\n        categoryAxisMap.set('x', xModel);\n        categoryAxisMap.set('y', yModel);\n    },\n};\n\nfunction isCategory(axisModel: AxisBaseModel) {\n    return axisModel.get('type') === 'category';\n}\n\n","sourceCodeStart":204,"sourceCodeEnd":240,"githubUrl":"https://github.com/apache/echarts/blob/30076aedcd7b7f65d8dd8e8d9ece46ce778133a3/src/model/referHelper.ts#L204-L240","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["If using on-demand imports, register the matrix component before setOption: `import { MatrixComponent } from 'echarts/components'; echarts.use([MatrixComponent]);`","Add a top-level `matrix` option array that defines the x/y dimensions the series references, e.g. `matrix: [{ x: {...}, y: {...} }]`.","Verify `matrixIndex`/`matrixId` on the series matches an existing matrix component (or omit them to use the first matrix as default).","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.)."],"exampleFix":"// before\nimport * as echarts from 'echarts/core';\nimport { HeatmapChart } from 'echarts/charts';\necharts.use([HeatmapChart]);\nconst option = {\n  series: [{ type: 'heatmap', coordinateSystem: 'matrix', data: [...] }]\n  // no matrix component defined or registered\n};\n\n// after\nimport * as echarts from 'echarts/core';\nimport { HeatmapChart } from 'echarts/charts';\nimport { MatrixComponent } from 'echarts/components';\necharts.use([HeatmapChart, MatrixComponent]);\nconst option = {\n  matrix: [{ /* x/y layout config */ }],\n  series: [{ type: 'heatmap', coordinateSystem: 'matrix', data: [...] }]\n};","handlingStrategy":"validation","validationCode":"// Before chart.setOption, assert every series bound to 'matrix' has a matrix component\n// and that MatrixComponent is registered (on-demand builds).\nfunction assertMatrixReady(option, echartsRef) {\n  const seriesArr = [].concat(option.series || []);\n  const usesMatrix = seriesArr.some(s => s && s.coordinateSystem === 'matrix');\n  if (!usesMatrix) return;\n  if (!option.matrix || !option.matrix.length) {\n    throw new Error('Option uses coordinateSystem:\"matrix\" but defines no `matrix` component.');\n  }\n  // crude registration check: MatrixComponent registers a 'matrix' coordinate system\n  const inst = echartsRef.init(null, null, { ssr: true, width: 1, height: 1 });\n  try { inst.setOption({ matrix: [{}] }); } finally { inst.dispose(); }\n}","typeGuard":"// Narrow an option to the matrix-capable shape before relying on it.\nfunction isMatrixOption(option) {\n  return Array.isArray(option.matrix) && option.matrix.length > 0\n    && Array.isArray(option.series)\n    && option.series.some(s => s && s.coordinateSystem === 'matrix');\n}","tryCatchPattern":null,"preventionTips":["Whenever a series sets `coordinateSystem: 'matrix'`, always pair it with a `matrix: [...]` option block in the same PR/review.","In on-demand builds, keep the `echarts.use([...])` list in one module and review it together with the option types you support.","Run against a dev/non-minified build during development so this `__DEV__`-only throw surfaces as a clear message rather than a null dereference in production."],"tags":["coordinate-system","matrix","configuration","on-demand-import"],"backgroundTag":null,"analyzedSha":"30076aedcd7b7f65d8dd8e8d9ece46ce778133a3","analyzedAt":"2026-08-12T12:42:28.134Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}