{"record":{"id":"7d368adbb82abb04","repo":"BabylonJS/Babylon.js","slug":"plugin-version-is-incorrect-expected-version-2-7d368a","errorCode":null,"errorMessage":"Plugin version is incorrect. Expected version 2.","messagePattern":"Plugin version is incorrect\\. Expected version 2\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/dev/core/src/Physics/v2/physicsShape.ts","lineNumber":75,"sourceCode":"     *  * parameters: The parameters of the shape.\r\n     *  * pluginData: The plugin data of the shape. This is used if you already have a reference to the object on the plugin side.\r\n     * You need to specify either type or pluginData.\r\n     * @param scene The scene the shape belongs to.\r\n     *\r\n     * This code is useful for creating a new physics shape with the given type, options, and scene.\r\n     * It also checks that the physics engine and plugin version are correct.\r\n     * If not, it throws an error. This ensures that the shape is created with the correct parameters and is compatible with the physics engine.\r\n     */\r\n    constructor(options: PhysicShapeOptions, scene: Scene) {\r\n        if (!scene) {\r\n            return;\r\n        }\r\n        const physicsEngine = scene.getPhysicsEngine();\r\n        if (!physicsEngine) {\r\n            throw new Error(\"No Physics Engine available.\");\r\n        }\r\n        if (physicsEngine.getPluginVersion() != 2) {\r\n            throw new Error(\"Plugin version is incorrect. Expected version 2.\");\r\n        }\r\n        const physicsPlugin = physicsEngine.getPhysicsPlugin();\r\n        if (!physicsPlugin) {\r\n            throw new Error(\"No Physics Plugin available.\");\r\n        }\r\n        this._physicsPlugin = physicsPlugin as IPhysicsEnginePluginV2;\r\n\r\n        if (options.pluginData !== undefined && options.pluginData !== null) {\r\n            this._pluginData = options.pluginData;\r\n            this._type = this._physicsPlugin.getShapeType(this);\r\n        } else if (options.type !== undefined && options.type !== null) {\r\n            this._type = options.type;\r\n            const parameters = options.parameters ?? {};\r\n            this._physicsPlugin.initShape(this, options.type, parameters);\r\n        }\r\n    }\r\n\r\n    /**\r","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/BabylonJS/Babylon.js/blob/0592b347b8a4ee0236089ea86a749cacfdb266d8/packages/dev/core/src/Physics/v2/physicsShape.ts#L57-L93","documentation":"PhysicsShape is part of the v2 API and requires a plugin reporting `getPluginVersion() == 2`. Scenes enabled with legacy v1 plugins (Cannon/Ammo/Oimo) fail this check when a shape is constructed.","triggerScenarios":"Constructing `new PhysicsShape(options, scene)` in a scene enabled with a v1 plugin such as `new CannonJSPlugin()` or `new AmmoJSPlugin()`.","commonSituations":"Mixed-version code: v1 impostors plus new v2 shapes in one scene; old enablePhysics call left in place during a Havok migration; bundling the wrong @babylonjs/core version where the plugin defaults to v1.","solutions":["Enable physics with a v2 plugin (`HavokPlugin`) instead of v1 plugins","Ensure `physicsEngine.getPluginVersion()` returns 2 by using the @babylonjs/havok integration","Replace all v1 impostor usage with v2 bodies/shapes for consistency"],"exampleFix":"// before\nscene.enablePhysics(gravity, new AmmoJSPlugin());\nconst shape = new PhysicsShape(options, scene); // version error\n// after\nconst havok = await HavokPhysics();\nscene.enablePhysics(gravity, new HavokPlugin(true, havok));\nconst shape = new PhysicsShape(options, scene);","handlingStrategy":"validation","validationCode":"if (scene.getPhysicsEngine()?.getPluginVersion() !== 2) {\n  throw new Error('PhysicsShape requires a v2 physics plugin (HavokPlugin)');\n}","typeGuard":"function hasV2Plugin(scene: BABYLON.Scene): boolean {\n  return scene.getPhysicsEngine()?.getPluginVersion() === 2;\n}","tryCatchPattern":"try {\n  const shape = new PhysicsShape(options, scene);\n} catch (e) {\n  if (e.message.includes('Plugin version')) {\n    // switch enablePhysics to a v2 plugin\n  }\n}","preventionTips":["Standardize on HavokPlugin for v2 physics; remove legacy plugin imports","Add a startup assertion for getPluginVersion() === 2","Audit enablePhysics call sites when upgrading from v1 impostors"],"tags":["physics","version-mismatch","babylonjs"],"backgroundTag":"plugin-version-mismatch","analyzedSha":"0592b347b8a4ee0236089ea86a749cacfdb266d8","analyzedAt":"2026-08-30T15:11:20.442Z","schemaVersion":2},"datasetVersion":"2026-08-30T18:17:15.746Z"}