BabylonJS/Babylon.js · error

Plugin version is incorrect. Expected version 2.

Error message

Plugin version is incorrect. Expected version 2.

What it means

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.

Source

Thrown at packages/dev/core/src/Physics/v2/physicsShape.ts:75

     *  * parameters: The parameters of the shape.
     *  * pluginData: The plugin data of the shape. This is used if you already have a reference to the object on the plugin side.
     * You need to specify either type or pluginData.
     * @param scene The scene the shape belongs to.
     *
     * This code is useful for creating a new physics shape with the given type, options, and scene.
     * It also checks that the physics engine and plugin version are correct.
     * If not, it throws an error. This ensures that the shape is created with the correct parameters and is compatible with the physics engine.
     */
    constructor(options: PhysicShapeOptions, scene: Scene) {
        if (!scene) {
            return;
        }
        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;

        if (options.pluginData !== undefined && options.pluginData !== null) {
            this._pluginData = options.pluginData;
            this._type = this._physicsPlugin.getShapeType(this);
        } else if (options.type !== undefined && options.type !== null) {
            this._type = options.type;
            const parameters = options.parameters ?? {};
            this._physicsPlugin.initShape(this, options.type, parameters);
        }
    }

    /**

View on GitHub (pinned to 0592b347b8)

Solutions

1. Enable physics with a v2 plugin (`HavokPlugin`) instead of v1 plugins
2. Ensure `physicsEngine.getPluginVersion()` returns 2 by using the @babylonjs/havok integration
3. Replace all v1 impostor usage with v2 bodies/shapes for consistency

Example fix

// before
scene.enablePhysics(gravity, new AmmoJSPlugin());
const shape = new PhysicsShape(options, scene); // version error
// after
const havok = await HavokPhysics();
scene.enablePhysics(gravity, new HavokPlugin(true, havok));
const shape = new PhysicsShape(options, scene);

if (scene.getPhysicsEngine()?.getPluginVersion() !== 2) {
  throw new Error('PhysicsShape requires a v2 physics plugin (HavokPlugin)');
}

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

try {
  const shape = new PhysicsShape(options, scene);
} catch (e) {
  if (e.message.includes('Plugin version')) {
    // switch enablePhysics to a v2 plugin
  }
}

When it happens

Trigger: Constructing `new PhysicsShape(options, scene)` in a scene enabled with a v1 plugin such as `new CannonJSPlugin()` or `new AmmoJSPlugin()`.

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

Related errors

• Plugin version is incorrect. Expected version 2.
• Could not find signal input with name ${name} in block ${cla
• Could not find signal output with name ${name} in block ${cl
• No Physics Engine available.
• No Physics Plugin available.

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