apache/echarts · error · Error

{mainType}.type should be specified.

Error message

{mainType}.type should be specified.

What it means

Thrown by the class-manager's `getClass(mainType, subType, throwWhenNotFound)` in clazz.ts:289. It fires only when the caller passes `throwWhenNotFound === true`, the lookup found no registered class under `mainType`, AND no `subType` was supplied (the `!subType` branch). The interpolated message `mainType + '.type should be specified.'` is the library's way of saying "no class is registered for component main type X". Unlike most dev errors in this file, this throw is NOT gated by `__DEV__` — it is produced whenever the internal caller marks the lookup mandatory, so it can occur in production bundles.

Source

Thrown at src/util/clazz.ts:289

                container[componentTypeInfo.sub] = clz;
            }
        }
        return clz;
    };

    target.getClass = function (
        mainType: ComponentMainType,
        subType?: ComponentSubType,
        throwWhenNotFound?: boolean
    ): Constructor {
        let clz = storage[mainType];

        if (clz && (clz as SubclassContainer)[IS_CONTAINER]) {
            clz = subType ? (clz as SubclassContainer)[subType] : null;
        }

        if (throwWhenNotFound && !clz) {
            throw new Error(
                !subType
                    ? mainType + '.' + 'type should be specified.'
                    : 'Component ' + mainType + '.' + (subType || '') + ' is used but not imported.'
            );
        }

        return clz as Constructor;
    };

    target.getClassesByMainType = function (componentType: ComponentFullType): Constructor[] {
        const componentTypeInfo = parseClassType(componentType);

        const result: Constructor[] = [];
        const obj = storage[componentTypeInfo.main];

        if (obj && (obj as SubclassContainer)[IS_CONTAINER]) {
            zrUtil.each(obj as SubclassContainer, function (o, type) {
                type !== IS_CONTAINER && result.push(o as Constructor);

View on GitHub (pinned to 30076aedcd)

Solutions

1. Register the missing component named in the message: e.g. `import { GridComponent } from 'echarts/components'; echarts.use([GridComponent]);` (substitute the mainType from the error).
2. Audit your `echarts.use([...])` list against every component `type` / coordinate-system component referenced in your option.
3. If you did not intend to use on-demand imports, switch to the full bundle: `import * as echarts from 'echarts';` which registers all built-ins.
4. Check the spelling of the offending `type` value in your option against the registered component names.

Example fix

// before
import * as echarts from 'echarts/core';
import { BarChart } from 'echarts/charts';
echarts.use([BarChart]); // GridComponent missing -> 'grid.type should be specified.'
const option = { xAxis: { type: 'category' }, yAxis: {}, series: [{ type: 'bar' }] };

// after
import * as echarts from 'echarts/core';
import { BarChart } from 'echarts/charts';
import { GridComponent } from 'echarts/components';
echarts.use([BarChart, GridComponent]);
const option = { xAxis: { type: 'category' }, yAxis: {}, series: [{ type: 'bar' }] };

// Validate that every component main type referenced by the option is registered,
// by attempting a throwaway setOption on a hidden instance and catching the error.
function validateRegistrations(echartsRef, option) {
  const probe = echartsRef.init(document.createElement('div'));
  try {
    probe.setOption(option, true);
  } catch (e) {
    throw new Error('Unregistered component detected before render: ' + e.message);
  } finally {
    probe.dispose();
  }
}

When it happens

Trigger: An internal call like `getClass('grid', undefined, true)` (or any single-class main type such as `xAxis`, `singleAxis`, `polar`) where that component main type was never registered. The typical cause in user code is an on-demand build (`echarts/core`) that references a component whose module was omitted from `echarts.use([...])`, so `storage[mainType]` is empty.

Common situations: Migrating from the full `echarts` import to tree-shaken `echarts/core` and leaving some components (grid, polar, radar, etc.) out of `.use()`; using a trimmed bundle (`echarts.simple`/`echarts.common`) that excludes the referenced component; a typo in a component's `type` field that resolves to an unregistered main type; a custom component whose `registerClass`/install was never invoked.

Related errors

• Component {mainType}.{subType} is used but not imported.
• matrix coordinate system should be specified.
• Only one bmap component can exist
• Heatmap must use with visualMap
• levels[i].depth is mandatory and should be natural number

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