MouseConstraint.create: options.mouse was undefined, options

Error message

MouseConstraint.create: options.mouse was undefined, options.element was undefined, may not function as expected

What it means

MouseConstraint.create was called with no engine.render.canvas and no options.element, so a Mouse could not be bound to any canvas. A default Mouse with no element is created and a warning is emitted; the constraint will exist but mouse interaction will not track pointer events correctly (mouse.position stays at origin).

Source

Thrown at src/constraint/MouseConstraint.js:45

     * Creates a new mouse constraint.
     * All properties have default values, and many are pre-calculated automatically based on other properties.
     * See the properties section below for detailed information on what you can pass via the `options` object.
     * @method create
     * @param {engine} engine
     * @param {} options
     * @return {MouseConstraint} A new MouseConstraint
     */
    MouseConstraint.create = function(engine, options) {
        var mouse = (engine ? engine.mouse : null) || (options ? options.mouse : null);

        if (!mouse) {
            if (engine && engine.render && engine.render.canvas) {
                mouse = Mouse.create(engine.render.canvas);
            } else if (options && options.element) {
                mouse = Mouse.create(options.element);
            } else {
                mouse = Mouse.create();
                Common.warn('MouseConstraint.create: options.mouse was undefined, options.element was undefined, may not function as expected');
            }
        }

        var constraint = Constraint.create({ 
            label: 'Mouse Constraint',
            pointA: mouse.position,
            pointB: { x: 0, y: 0 },
            length: 0.01, 
            stiffness: 0.1,
            angularStiffness: 1,
            render: {
                strokeStyle: '#90EE90',
                lineWidth: 3
            }
        });

        var defaults = {
            type: 'mouseConstraint',

View on GitHub (pinned to acb99b6f87)

Solutions

Pass options.element: MouseConstraint.create(engine, { element: canvasElement }).
If using Matter.Render, pass the engine with an initialized render: ensure Render.create ran and engine.render.canvas exists.
Create the Mouse yourself: options.mouse = Mouse.create(canvas).
If truly headless, use your own input handling instead of MouseConstraint.

Example fix

// before
const mc = MouseConstraint.create(engine); // no render, no element
// after
const mc = MouseConstraint.create(engine, { element: document.querySelector('canvas') });

Defensive patterns

Strategy: validation

Validate before calling

function canCreateMouseConstraint(engine, options) {
  return Boolean(
    (engine && engine.render && engine.render.canvas) ||
    (options && options.element) ||
    (options && options.mouse)
  );
}

Type guard

function hasMouseTarget(engine, options) {
  return !!(options?.mouse || options?.element || engine?.render?.canvas);
}

Prevention

Pass { element: canvas } explicitly when creating without a render
Initialize Render.create before MouseConstraint if relying on engine.render.canvas
Build Mouse yourself with Mouse.create(canvas) for custom setups
Remember MouseConstraint needs a DOM canvas; headless engines need custom input handling

When it happens

Trigger: MouseConstraint.create({ mouse: undefined, element: undefined }) with no engine, or an engine created without Render (engine.render undefined), so neither fallback source for a canvas exists.

Common situations: Headless engine (Render.create never called) plus MouseConstraint; passing options in the wrong field (e.g. { canvas } instead of { element }); forgetting options entirely.

Understand the failure class

Background: "Must pass :limit option" / "Missing required option" — required option errors explained — this error's family across 41 libraries.

Related errors

AI-assisted analysis of liabru/matter-js@acb99b6f87 (2026-09-02). Data as JSON: /api/errors/dbf33dd6bbd54173. Report an issue: GitHub.