The `${pluginKey}` plugin cannot be used with the `${incompa

Error message

The `${pluginKey}` plugin cannot be used with the `${incompatibleSettingKey}` option. This combination is not supported. The plugin will remain disabled.

What it means

Plugins can declare hard conflicts with certain grid settings. When such a plugin is enabled (at init or during updateSettings), BasePlugin.isHardConflictBlocked() checks getHardConflict() against the current settings; on conflict it warns that the combination is unsupported and the plugin stays disabled instead of operating in a broken state.

Source

Thrown at handsontable/src/plugins/base/base.ts:251

    }

    this.initialized = true;
  }

  /**
   * Whether this plugin is blocked by a registered hard conflict (another top-level setting is truthy; for example
   * nestedRows blocks pagination, or manualRowMove blocks dataProvider). Emits a console warning when blocked.
   *
   * @returns {boolean} true if the plugin must not enable.
   */
  isHardConflictBlocked() {
    const pluginKey = this.constructor.PLUGIN_KEY;
    const conflict = getHardConflict(this.hot.getSettings(), pluginKey);

    if (conflict) {
      const { incompatibleSettingKey } = conflict;

      warn(toSingleLine`The \`${pluginKey}\` plugin cannot be used with the \`${incompatibleSettingKey}\` option.\x20
        This combination is not supported. The plugin will remain disabled.`);

      return true;
    }

    return false;
  }

  /**
   * Enable plugin for this Handsontable instance.
   */
  enablePlugin(): void {
    this.enabled = true;
  }

  /**
   * Disable plugin for this Handsontable instance.
   */

View on GitHub (pinned to 2c365a3291)

Solutions

Read the warning: it names the exact conflicting option key
Remove or disable the conflicting option in your settings object
Decide which feature you need — you cannot have both; restructure the config
Update Handsontable if a newer release lifted the incompatibility

Example fix

// before
new Handsontable(el, { rowHeaders: true, columnSorting: true, /* + conflicting option */ fixedRowsTop: 3, ... });
// after
new Handsontable(el, { columnSorting: true }); // conflicting option removed

Defensive patterns

Strategy: validation

Validate before calling

const HARD_CONFLICTS = { somePlugin: ['conflictingOption'] }; // see plugin docs
const conflicting = (HARD_CONFLICTS[pluginKey] || []).filter(k => k in settings);
if (conflicting.length) delete settings[conflicting[0]];

Prevention

Read each plugin's docs for declared incompatible options
Keep the grid settings object minimal and intentional
After updateSettings, verify the plugin actually enabled: hot.getPlugin('x').isEnabled === true

When it happens

Trigger: Enabling a plugin while an incompatible option is set, e.g. columnSorting with a conflicting setting per the plugin's hard-conflict map; calling updateSettings to turn on the conflicting option while the plugin is active.

Common situations: Turning on two features designed to be mutually exclusive (e.g. certain manual-move/fixed-rows combos, or a plugin vs nestedRows/trimRows style conflicts); copying a config that mixes incompatible options.

Related errors

AI-assisted analysis of handsontable/handsontable@2c365a3291 (2026-09-01). Data as JSON: /api/errors/7283ccc31d4d950c. Report an issue: GitHub.