{"record":{"id":"48678e7b2a63a21e","repo":"swc-project/swc","slug":"plugin-s-ast-schema-version-is-not-compatible-with","errorCode":null,"errorMessage":"Plugin's AST schema version is not compatible with host's. Host: {}, Plugin: {}","messagePattern":"Plugin's AST schema version is not compatible with host's\\. Host: (.+?), Plugin: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/swc_plugin_runner/src/transform_executor.rs","lineNumber":126,"sourceCode":"     * the host. Returns true if it's compatible, false otherwise.\n     *\n     * Host should appropriately handle if plugin is not compatible to the\n     * current runtime.\n     */\n    #[allow(unreachable_code)]\n    pub fn is_transform_schema_compatible(&mut self) -> Result<(), Error> {\n        #[cfg(any(\n            feature = \"plugin_transform_schema_v1\",\n            feature = \"plugin_transform_schema_vtest\"\n        ))]\n        return {\n            let host_schema_version = PLUGIN_TRANSFORM_AST_SCHEMA_VERSION;\n\n            // TODO: this is incomplete\n            if host_schema_version >= self.plugin_core_diag.ast_schema_version {\n                Ok(())\n            } else {\n                anyhow::bail!(\n                    \"Plugin's AST schema version is not compatible with host's. Host: {}, Plugin: \\\n                     {}\",\n                    host_schema_version,\n                    self.plugin_core_diag.ast_schema_version\n                )\n            }\n        };\n\n        #[cfg(not(all(\n            feature = \"plugin_transform_schema_v1\",\n            feature = \"plugin_transform_schema_vtest\"\n        )))]\n        anyhow::bail!(\n            \"Plugin runner cannot detect plugin's schema version. Ensure host is compiled with \\\n             proper versions\"\n        )\n    }\n}","sourceCodeStart":108,"sourceCodeEnd":144,"githubUrl":"https://github.com/swc-project/swc/blob/5176682b65416c6b5de6b47379ae1588ea3ecb3f/crates/swc_plugin_runner/src/transform_executor.rs#L108-L144","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before (package.json): mismatched versions\n\"@swc/core\": \"1.3.80\",\n\"@swc/plugin-x\": \"^0.5.0\" # built against swc_core 1.3.100+\n\n# after\n\"@swc/core\": \"^1.3.100\",\n\"@swc/plugin-x\": \"^0.5.0\"","handlingStrategy":"validation","validationCode":"// At install/startup, reject plugin/host combinations before running transforms\nconst hostVer = require('@swc/core/package.json').version;\nconst pluginPeer = require('@swc-jest/core/package.json').peerDependencies?.['@swc/core'];\nif (pluginPeer && !require('semver').satisfies(hostVer, pluginPeer)) {\n  throw new Error(`Plugin requires @swc/core ${pluginPeer}, host has ${hostVer}`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await transform(src, { jsc: { experimental: { plugins: [[plugin, {}]] } } });\n} catch (e) {\n  if (/AST schema version is not compatible/.test(e.message)) throw new Error('Upgrade @swc/core to match the plugin build');\n  throw e;\n}","preventionTips":["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"],"tags":["swc-plugin","version-mismatch","ast-schema","compatibility","wasm-plugin"],"backgroundTag":"plugin-schema-version-mismatch","analyzedSha":"5176682b65416c6b5de6b47379ae1588ea3ecb3f","analyzedAt":"2026-08-17T16:16:52.067Z","contentChangedAt":"2026-08-17T16:16:52.067Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}