Plugin runner cannot detect plugin's schema version. Ensure…

Error message

Plugin runner cannot detect plugin's schema version. Ensure host is compiled with proper versions

What it means

The sibling of the schema check: when the host was compiled without any of the plugin transform schema features (plugin_transform_schema_v1 / plugin_transform_schema_vtest), the cfg(not(all(...))) branch unconditionally bails with 'Plugin runner cannot detect plugin's schema version'. It is a build-configuration error: this swc_plugin_runner build has no AST schema knowledge at all, so it cannot even compare versions with a plugin.

Solutions

Enable the `plugin_transform_schema_v1` feature (via swc_core's plugin feature set) on the host build
Restore default features if you trimmed them without intending to drop plugin support
If plugins are genuinely unsupported in your build, stop configuring plugin entries rather than relying on them

Example fix

# before
swc_core = { version = "...", default-features = false, features = ["ecma_transforms"] }

# after
swc_core = { version = "...", default-features = false, features = [
  "ecma_transforms",
  "ecma_plugin_transform", # enables plugin_transform_schema_v1
] }

Defensive patterns

Strategy: validation

Validate before calling

# Fail fast at build time if the host lacks plugin schema support
cargo tree -i swc_plugin_runner -f "{f}" | grep -q plugin_transform_schema_v1 || echo 'WARN: plugin transforms will always fail'

Try / catch

match executor.is_transform_schema_compatible() {
    Ok(()) => { /* run plugin */ }
    Err(e) if e.to_string().contains("cannot detect plugin's schema version") => {
        // host built without schema features: rebuild with plugin_transform_schema_v1 or disable plugins
    }
    Err(e) => return Err(e),
}

Prevention

When trimming swc_core default features, explicitly keep the plugin transform feature set if you load plugins
Add a build check (cargo tree) that plugin schema features are present when plugin config exists
Document required cargo features next to plugin configuration in your build scripts

When it happens

Trigger: Compiling swc_plugin_runner (or swc_core's plugin transform integration) with the schema features disabled, then attempting any plugin transform — is_transform_schema_compatible always bails regardless of the plugin.

Common situations: Custom builds of swc_core with a trimmed feature set; downstream crates overriding default features and accidentally dropping plugin_transform_schema_v1; wasm/embedded hosts compiled with a minimal feature graph.

Related errors

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

Appendix: source

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

            // 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"
        )
    }
}

/// A struct encapsule executing a plugin's transform.
pub struct TransformExecutor {
    source_map: Arc<SourceMap>,
    unresolved_mark: swc_common::Mark,
    metadata_context: Arc<TransformPluginMetadataContext>,
    plugin_env_vars: Option<Arc<Vec<swc_atoms::Atom>>>,
    plugin_config: Option<serde_json::Value>,
    module_bytes: Box<dyn PluginModuleBytes>,
    runtime: Arc<dyn runtime::Runtime>,
}

#[cfg(feature = "encoding-impl")]

View on GitHub (pinned to 5176682b65)