Physics Engine ${this._physicsPlugin.name} cannot be found.

Error message

Physics Engine ${this._physicsPlugin.name} cannot be found. Please make sure it is included.

What it means

The legacy V1 PhysicsEngine requires a physics plugin (e.g. Cannon.js, Oimo.js via IPhysicsEnginePlugin) that reports isSupported() === true, which the plugin sets only when its underlying library has loaded and registered. The default plugin factory yields an unsupported placeholder, so if no real plugin is supplied or its library failed to load, the constructor throws.

Source

Thrown at packages/dev/core/src/Physics/v1/physicsEngine.ts:54

     * @virtual
     * Factory used to create the default physics plugin.
     * @returns The default physics plugin
     */
    public static DefaultPluginFactory(): IPhysicsEnginePlugin {
        throw _WarnImport("CannonJSPlugin");
    }

    /**
     * Creates a new Physics Engine
     * @param gravity defines the gravity vector used by the simulation
     * @param _physicsPlugin defines the plugin to use (CannonJS by default)
     */
    constructor(
        gravity: Nullable<Vector3>,
        private _physicsPlugin: IPhysicsEnginePlugin = PhysicsEngine.DefaultPluginFactory()
    ) {
        if (!this._physicsPlugin.isSupported()) {
            throw new Error("Physics Engine " + this._physicsPlugin.name + " cannot be found. " + "Please make sure it is included.");
        }
        gravity = gravity || new Vector3(0, -9.807, 0);
        this.setGravity(gravity);
        this.setTimeStep();
    }

    /**
     * Sets the gravity vector used by the simulation
     * @param gravity defines the gravity vector to use
     */
    public setGravity(gravity: Vector3): void {
        this.gravity = gravity;
        this._physicsPlugin.setGravity(this.gravity);
    }

    /**
     * Set the time step of the physics engine.
     * Default is 1/60.

View on GitHub (pinned to 0592b347b8)

Solutions

Import/install the physics library and plugin (e.g. cannon.js) and pass its plugin factory to scene.enablePhysics before constructing a PhysicsEngine.
Ensure the physics library script loads before enablePhysics is called (await import or load order).
Verify network/CDN availability in production builds; bundle the physics library locally instead.

Example fix

// before
scene.enablePhysics(new Vector3(0, -9.8, 0)); // no plugin
// after
import { CannonJSPlugin } from "@babylonjs/core";
import * as CANNON from "cannon";
scene.enablePhysics(new Vector3(0, -9.8, 0), new CannonJSPlugin(true, 10, CANNON));

Defensive patterns

Strategy: validation

Validate before calling

if (!plugin || !plugin.isSupported()) {
  throw new Error("Load the physics library (e.g. cannon.js) and pass its plugin to enablePhysics");
}

Type guard

function isPluginReady(p: IPhysicsEnginePlugin | undefined): p is IPhysicsEnginePlugin {
  return !!p && typeof p.isSupported === "function" && p.isSupported();
}

Try / catch

try {
  const engine = new PhysicsEngine(gravity, new CannonJSPlugin(true, 10, CANNON));
} catch (e) {
  if (e.message.includes("cannot be found")) {
    console.error("Physics library not loaded before PhysicsEngine construction");
  }
}

Prevention

Load the physics library (CANNON/Oimo) before calling scene.enablePhysics.
Always pass an explicit plugin; never rely on DefaultPluginFactory placeholder.
Verify CDN availability and add fallback local bundling of the physics lib.

When it happens

Trigger: new PhysicsEngine(gravity) with no plugin argument; or scene.enablePhysics(gravity, plugin) where the plugin's isSupported() returns false because the physics library (e.g. window.CANNON) isn't loaded.

Common situations: Forgetting to include the cannon.js/oimo.js <script> or npm import; physics script loaded after scene creation; CDN load failure offline; enabling physics before the plugin library finished loading.

Related errors

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