swc-project/swc · error · anyhow::Error

Plugin's AST schema version is not compatible with host's. H

Error message

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

What it means

Version gate in TransformExecutor::is_transform_schema_compatible: the host's PLUGIN_TRANSFORM_AST_SCHEMA_VERSION must be >= the plugin's ast_schema_version (read from PluginCorePkgDiagnostics). If the plugin was compiled against a newer AST schema than the host understands, serialized ASTs are incompatible and the runner refuses to execute before touching your code.

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 d7d7434666)

Solutions

1. Upgrade the host (@swc/core or your swc_core dependency) to at least the plugin's schema version, then retry
2. Or rebuild the plugin against the older swc_core matching the host
3. Print both versions from the error (Host: x, Plugin: y) to decide which side to move

Example fix

# before: host pinned old, plugin newer
@swc/core@1.3.40 + plugin built with swc_core@10

# after: align by upgrading the host
@swc/core@latest  # host schema >= plugin schema

// Rust: preflight compatibility when you control both versions
// (mirrors the host check host >= plugin)
fn schema_ok(host_version: u32, plugin_version: u32) -> bool {
    host_version >= plugin_version
}
// obtain plugin_version from the plugin's diagnostics/manifest before loading

match plugins.load(...) {
    Err(e) if e.to_string().contains("AST schema version is not compatible") => {
        // message carries Host: x, Plugin: y - parse and tell the user which side to bump
        return Err(e.context("upgrade @swc/core (host) or rebuild the plugin against the host's swc_core"));
    }
    other => other,
}

When it happens

Trigger: Loading a wasm plugin built with a newer swc_core than the host's swc_core/plugin runner - e.g. updating a published plugin while pinning an old @swc/core, or the reverse drift in a monorepo mixing versions.

Common situations: npm lockfiles keeping an old @swc/core while a sibling dependency ships a newer first-party plugin; locally developed plugins rebuilt against latest swc_core and tested against an older embedded host.

Related errors

• Failed to convert pointer size to calculate: {msg}
• {msg}
• Failed to resolve plugin path: {resolved_path:?}
• Failed to serialize output: {e}
• Failed to unwrap Arc: other references to transform_result e

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