BabylonJS/Babylon.js · error

Unsupported Constraint Type.

Error message

Unsupported Constraint Type.

What it means

HavokPlugin supports a fixed set of joint types (ball and socket, hinge, prismatic, slider, fixed, six dof). When building a constraint it switches on PhysicsConstraintType; any other value has no corresponding Havok joint and reaches the else throw. The constraint is never created or enabled in that case.

Source

Thrown at packages/dev/core/src/Physics/v2/Plugins/havokPlugin.ts:2265

                    if (l.minLimit != undefined) {
                        this._hknp.HP_Constraint_SetAxisMode(jointId, axId, this._hknp.ConstraintAxisLimitMode.LIMITED);
                        this._hknp.HP_Constraint_SetAxisMinLimit(jointId, axId, l.minLimit);
                    }

                    if (l.maxLimit != undefined) {
                        this._hknp.HP_Constraint_SetAxisMode(jointId, axId, this._hknp.ConstraintAxisLimitMode.LIMITED);
                        this._hknp.HP_Constraint_SetAxisMaxLimit(jointId, axId, l.maxLimit);
                    }
                }
                if (l.stiffness) {
                    this._hknp.HP_Constraint_SetAxisStiffness(jointId, axId, l.stiffness);
                }
                if (l.damping) {
                    this._hknp.HP_Constraint_SetAxisDamping(jointId, axId, l.damping);
                }
            }
        } else {
            throw new Error("Unsupported Constraint Type.");
        }

        const collisionEnabled = !!options.collision;
        this._hknp.HP_Constraint_SetCollisionsEnabled(jointId, collisionEnabled);
        this._hknp.HP_Constraint_SetEnabled(jointId, true);
    }

    /**
     * Get a list of all the pairs of bodies that are connected by this constraint.
     * @param constraint the constraint to search from
     * @returns a list of parent, child pairs
     */
    getBodiesUsingConstraint(constraint: PhysicsConstraint): ConstrainedBodyPair[] {
        const pairs: ConstrainedBodyPair[] = [];
        for (const jointId of constraint._pluginData) {
            const bodyIds = this._constraintToBodyIdPair.get(jointId[0]);
            if (bodyIds) {
                const parentBodyInfo = this._bodies.get(bodyIds[0]);

View on GitHub (pinned to 0592b347b8)

Solutions

1. Use one of the mapped types: BALL_AND_SOCKET, HINGE, PRISMATIC, SLIDER, FIXED, SIX_DOF (via Physics6DoFConstraint).
2. Replace unsupported types with the closest supported joint (e.g. LOCK/FIX behaviors via SIX_DOF limits).
3. Verify the type value is the imported enum member and not a stale numeric constant from the v1 API.

Example fix

// before
const c = new PhysicsConstraint(PhysicsConstraintType.LOCK, params, scene);
// after
const c = new PhysicsConstraint(PhysicsConstraintType.FIXED, params, scene);

const SUPPORTED = [PhysicsConstraintType.BALL_AND_SOCKET, PhysicsConstraintType.HINGE, PhysicsConstraintType.PRISMATIC, PhysicsConstraintType.SLIDER, PhysicsConstraintType.FIXED];
if (!SUPPORTED.includes(type)) {
  throw new Error(`unsupported constraint type for Havok: ${type}; use SIX_DOF via Physics6DoFConstraint for complex joints`);
}

function isSupportedConstraintType(t: unknown): t is PhysicsConstraintType {
  return [PhysicsConstraintType.BALL_AND_SOCKET, PhysicsConstraintType.HINGE, PhysicsConstraintType.PRISMATIC, PhysicsConstraintType.SLIDER, PhysicsConstraintType.FIXED].includes(t as PhysicsConstraintType);
}

When it happens

Trigger: new PhysicsConstraint(PhysicsConstraintType.LOCK, params, scene) or passing an invalid/undefined constraint type, so the joint-creation switch in HavokPlugin falls through to the throw at havokPlugin.ts:2265.

Common situations: Using a constraint type that exists in the Babylon enum but is not mapped for Havok; passing a numeric type from old code written for the v1 physics API; typos or custom numbers cast to PhysicsConstraintType.

Related errors

• Unknown motion type: ${type}
• No mesh provided to create physics shape.
• Missing required heightfield parameters
• Unsupported Shape Type.
• Missing scene parameter for constraint constructor.

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