BabylonJS/Babylon.js · error

Missing scene parameter for constraint constructor.

Error message

Missing scene parameter for constraint constructor.

What it means

PhysicsConstraint's constructor requires a Scene to look up the physics engine and plugin version before creating the constraint. Passing null/undefined for scene trips the first guard and throws immediately, since without a scene no engine or plugin can be resolved.

Source

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

    protected _type: PhysicsConstraintType;
    /**
     * @internal
     * The internal options that were used to init the constraint
     */
    public _initOptions?: PhysicsConstraintParameters;

    /**
     * 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;
    }

View on GitHub (pinned to 0592b347b8)

Solutions

1. Pass the live Scene as the third argument: new PhysicsConstraint(type, params, scene).
2. Ensure the scene variable is fully initialized (await engine.createSceneAsync() if async) before constructing the constraint.
3. Add an if (!scene) guard or assertion in your setup code before creating any constraints.

Example fix

// before
const constraint = new PhysicsConstraint(PhysicsConstraintType.BALL_AND_SOCKET, params, undefined);
// after
const constraint = new PhysicsConstraint(PhysicsConstraintType.BALL_AND_SOCKET, params, scene);

if (!(scene instanceof Scene)) {
  throw new Error("PhysicsConstraint requires a live Scene as its third argument");
}

function hasScene(s: unknown): s is Scene {
  return s instanceof Scene;
}

try {
  const constraint = new PhysicsConstraint(PhysicsConstraintType.BALL_AND_SOCKET, params, scene);
} catch (e) {
  if ((e as Error).message.includes("Missing scene parameter")) {
    console.error("Pass the live Scene instance as the third constructor argument", e);
  }
  throw e;
}

When it happens

Trigger: new PhysicsConstraint(PhysicsConstraintType.BALL_AND_SOCKET, params, undefined) — omitting the third scene argument, or passing a variable that is null because the scene was fetched too early (e.g. engine createScene not awaited).

Common situations: Copy-pasted constructor calls missing the scene argument; scene obtained from a factory returning a promise that was not awaited; refactoring code where the scene variable was renamed/shadowed to null.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Unsupported Constraint Type.
• No Physics Engine available.
• Plugin version is incorrect. Expected version 2.
• No Physics Plugin available.
• Unsupported Physics plugin version.

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