What causes "Plugin version is incorrect. Expected version 2." in BabylonJS/Babylon.js?

Switch to a v2 plugin: install @babylonjs/havok and pass `new HavokPlugin()` to `scene.enablePhysics()`

Plugin version is incorrect. Expected version 2.

Error message

Plugin version is incorrect. Expected version 2.

What it means

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.

Source

Thrown at packages/dev/core/src/Physics/v2/physicsConstraint.ts:54

    /**
     * Constructs a new constraint for the physics constraint.
     * @param type The type of constraint to create.
     * @param options The options for the constraint.
     * @param scene The scene the constraint belongs to.
     *
     * 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.
     * If all checks pass, it initializes the constraint with the given type and options.
     */
    constructor(type: PhysicsConstraintType, options: PhysicsConstraintParameters, scene: Scene) {
        if (!scene) {
            throw new Error("Missing scene parameter for constraint constructor.");
        }
        const physicsEngine = scene.getPhysicsEngine();
        if (!physicsEngine) {
            throw new Error("No Physics Engine available.");
        }
        if (physicsEngine.getPluginVersion() != 2) {
            throw new Error("Plugin version is incorrect. Expected version 2.");
        }
        const physicsPlugin = physicsEngine.getPhysicsPlugin();
        if (!physicsPlugin) {
            throw new Error("No Physics Plugin available.");
        }

        this._physicsPlugin = physicsPlugin as IPhysicsEnginePluginV2;
        this._options = options;
        this._type = type;
    }

    /**
     * Gets the type of the constraint.
     *
     * @returns The type of the constraint.
     *
     */
    public get type(): PhysicsConstraintType {

View on GitHub (pinned to 0592b347b8)

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

Example fix

// before
scene.enablePhysics(gravity, new CannonJSPlugin());
const constraint = new PhysicsConstraint(type, options, scene); // throws version error
// after
const havok = await HavokPhysics();
scene.enablePhysics(gravity, new HavokPlugin(true, havok));
const constraint = new PhysicsConstraint(type, options, scene);

Defensive patterns

Strategy: validation

Validate before calling

const engine = scene.getPhysicsEngine();
if (!engine || engine.getPluginVersion() !== 2) {
  throw new Error('A v2 physics plugin (e.g. HavokPlugin) is required');
}

Type guard

function isV2Physics(scene: BABYLON.Scene): boolean {
  return scene.getPhysicsEngine()?.getPluginVersion() === 2;
}

Try / catch

try {
  const constraint = new PhysicsConstraint(type, options, scene);
} catch (e) {
  if (e.message.includes('Plugin version')) {
    // recreate physics with a v2 plugin (Havok)
  }
}

Prevention

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

When it happens

Trigger: 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()`.

Common situations: 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.

Related errors

AI-assisted analysis of BabylonJS/Babylon.js@0592b347b8 (2026-08-30). Data as JSON: /api/errors/da6caae5203cc733. Report an issue: GitHub.