Plugin's AST schema version is not compatible with host's…

Q: What causes "Plugin's AST schema version is not compatible with host's. Host: {}, Plugin: {}" in swc-project/swc?

Upgrade the swc host (@swc/core, or the framework embedding it) to a version whose schema version is >= the plugin's

Error message

Plugin's AST schema version is not compatible with host's. Host: {}, Plugin: {}

What it means

Before running a plugin transform, TransformExecutor::is_transform_schema_compatible compares the host's compiled-in PLUGIN_TRANSFORM_AST_SCHEMA_VERSION with the version recorded in the plugin binary's metadata (plugin_core_diag.ast_schema_version). Because serialized AST exchange between host and plugin is only guaranteed when the host schema is not older than the plugin's, host < plugin bails with this incompatibility error. A plugin built against a newer swc_core cannot run on this host.

Solutions

Upgrade the swc host (@swc/core, or the framework embedding it) to a version whose schema version is >= the plugin's
Or pin the plugin to a version built against the swc_core version your host uses (check the plugin's swc_core dependency)
Verify both versions at install time (e.g. npm overrides/resolutions to keep swc family packages in lockstep)
After aligning, clear any on-disk plugin caches so stale serialized modules are not reused

Example fix

# before (package.json): mismatched versions
"@swc/core": "1.3.80",
"@swc/plugin-x": "^0.5.0" # built against swc_core 1.3.100+

# after
"@swc/core": "^1.3.100",
"@swc/plugin-x": "^0.5.0"

Defensive patterns

Strategy: validation

Validate before calling

// At install/startup, reject plugin/host combinations before running transforms
const hostVer = require('@swc/core/package.json').version;
const pluginPeer = require('@swc-jest/core/package.json').peerDependencies?.['@swc/core'];
if (pluginPeer && !require('semver').satisfies(hostVer, pluginPeer)) {
  throw new Error(`Plugin requires @swc/core ${pluginPeer}, host has ${hostVer}`);
}

Try / catch

try {
  await transform(src, { jsc: { experimental: { plugins: [[plugin, {}]] } } });
} catch (e) {
  if (/AST schema version is not compatible/.test(e.message)) throw new Error('Upgrade @swc/core to match the plugin build');
  throw e;
}

Prevention

Keep @swc/core, plugins, and frameworks that embed swc on compatible versions (npm overrides/resolutions)
Prefer plugins built against the same minor swc_core as your host
Verify plugin compatibility in CI with a smoke transform before the full build

When it happens

Trigger: Loading a .wasm plugin compiled with a newer swc_core (newer AST rkyv serialization schema) into a swc host whose PLUGIN_TRANSFORM_AST_SCHEMA_VERSION is lower, e.g. after upgrading the plugin but not the bundler, or pinning an old @swc/core while the plugin targets a newer schema.

Common situations: Version skew between @swc/core (or next.js' built-in swc) and plugins like @swc-jest, swc-plugin-* or community wasm plugins; CI locking the host but not plugins; local dev using latest plugin against older toolchain.

Related errors

AI-assisted analysis of swc-project/swc@5176682b65 (2026-08-17). Data as JSON: /api/errors/48678e7b2a63a21e. Report an issue: GitHub.

Appendix: source

Thrown at crates/swc_plugin_runner/src/transform_executor.rs:126

     * the host. Returns true if it's compatible, false otherwise.
     *
     * Host should appropriately handle if plugin is not compatible to the
     * current runtime.
     */
    #[allow(unreachable_code)]
    pub fn is_transform_schema_compatible(&mut self) -> Result<(), Error> {
        #[cfg(any(
            feature = "plugin_transform_schema_v1",
            feature = "plugin_transform_schema_vtest"
        ))]
        return {
            let host_schema_version = PLUGIN_TRANSFORM_AST_SCHEMA_VERSION;

            // TODO: this is incomplete
            if host_schema_version >= self.plugin_core_diag.ast_schema_version {
                Ok(())
            } else {
                anyhow::bail!(
                    "Plugin's AST schema version is not compatible with host's. Host: {}, Plugin: \
                     {}",
                    host_schema_version,
                    self.plugin_core_diag.ast_schema_version
                )
            }
        };

        #[cfg(not(all(
            feature = "plugin_transform_schema_v1",
            feature = "plugin_transform_schema_vtest"
        )))]
        anyhow::bail!(
            "Plugin runner cannot detect plugin's schema version. Ensure host is compiled with \
             proper versions"
        )
    }
}

View on GitHub (pinned to 5176682b65)