{"record":{"id":"da6caae5203cc733","repo":"BabylonJS/Babylon.js","slug":"plugin-version-is-incorrect-expected-version-2-da6caa","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/physicsConstraint.ts","lineNumber":54,"sourceCode":"    /**\r\n     * Constructs a new constraint for the physics constraint.\r\n     * @param type The type of constraint to create.\r\n     * @param options The options for the constraint.\r\n     * @param scene The scene the constraint belongs to.\r\n     *\r\n     * This code is useful for creating a new constraint for the physics engine. It checks if the scene has a physics engine, and if the plugin version is correct.\r\n     * If all checks pass, it initializes the constraint with the given type and options.\r\n     */\r\n    constructor(type: PhysicsConstraintType, options: PhysicsConstraintParameters, scene: Scene) {\r\n        if (!scene) {\r\n            throw new Error(\"Missing scene parameter for constraint constructor.\");\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\r\n        this._physicsPlugin = physicsPlugin as IPhysicsEnginePluginV2;\r\n        this._options = options;\r\n        this._type = type;\r\n    }\r\n\r\n    /**\r\n     * Gets the type of the constraint.\r\n     *\r\n     * @returns The type of the constraint.\r\n     *\r\n     */\r\n    public get type(): PhysicsConstraintType {\r","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/BabylonJS/Babylon.js/blob/0592b347b8a4ee0236089ea86a749cacfdb266d8/packages/dev/core/src/Physics/v2/physicsConstraint.ts#L36-L72","documentation":"The v2 constraint API only works with physics plugins exposing plugin version 2 (e.g. Havok). If the scene's physics engine was created with a legacy v1 plugin (e.g. old Cannon/Ammo/Oimo plugins), the version check `getPluginVersion() != 2` throws.","triggerScenarios":"Constructing a PhysicsConstraint in a scene whose physics engine was enabled with a v1 plugin such as `new CannonJSPlugin()` / `new AmmoJSPlugin()` instead of `new HavokPlugin()`.","commonSituations":"Migrating old projects from the v1 physics API (Cannon/Ammo/Oimo) to v2 (Havok) while keeping the old plugin; copy-pasted `enablePhysics` calls using legacy plugins.","solutions":["Switch to a v2 plugin: install @babylonjs/havok and pass `new HavokPlugin()` to `scene.enablePhysics()`","Update the `PhysicsEngineV2`-compatible import set (v2 classes live under Physics/v2)","Keep v1 constraint equivalents if you must stay on a v1 plugin"],"exampleFix":"// before\nscene.enablePhysics(gravity, new CannonJSPlugin());\nconst constraint = new PhysicsConstraint(type, options, scene); // throws version error\n// after\nconst havok = await HavokPhysics();\nscene.enablePhysics(gravity, new HavokPlugin(true, havok));\nconst constraint = new PhysicsConstraint(type, options, scene);","handlingStrategy":"validation","validationCode":"const engine = scene.getPhysicsEngine();\nif (!engine || engine.getPluginVersion() !== 2) {\n  throw new Error('A v2 physics plugin (e.g. HavokPlugin) is required');\n}","typeGuard":"function isV2Physics(scene: BABYLON.Scene): boolean {\n  return scene.getPhysicsEngine()?.getPluginVersion() === 2;\n}","tryCatchPattern":"try {\n  const constraint = new PhysicsConstraint(type, options, scene);\n} catch (e) {\n  if (e.message.includes('Plugin version')) {\n    // recreate physics with a v2 plugin (Havok)\n  }\n}","preventionTips":["Use HavokPlugin for all v2 physics work; avoid mixing v1 plugins with v2 classes","During migration from Cannon/Ammo, audit every enablePhysics call site","Assert plugin version once at startup"],"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"}