BabylonJS/Babylon.js · error · Error

step size should be less than 1.

Error message

step size should be less than 1.

What it means

PathCursor.move(step) advances the cursor along a Curve3 path by a relative amount. Because a single move must stay within one curve segment, absolute step values above 1 are rejected with this error; use multiple smaller moves instead.

Source

Thrown at packages/dev/core/src/Animations/pathCursor.ts:68

     * Moves the cursor behind by the step amount
     * @param step The amount to move the cursor back
     * @returns This path cursor
     */
    public moveBack(step: number = 0.002): PathCursor {
        this.move(-step);

        return this;
    }

    /**
     * Moves the cursor by the step amount
     * If the step amount is greater than one, an exception is thrown
     * @param step The amount to move the cursor
     * @returns This path cursor
     */
    public move(step: number): PathCursor {
        if (Math.abs(step) > 1) {
            throw new Error("step size should be less than 1.");
        }

        this.value += step;
        this._ensureLimits();
        this._raiseOnChange();

        return this;
    }

    /**
     * Ensures that the value is limited between zero and one
     * @returns This path cursor
     */
    private _ensureLimits(): PathCursor {
        while (this.value > 1) {
            this.value -= 1;
        }
        while (this.value < 0) {

View on GitHub (pinned to 0592b347b8)

Solutions

1. Clamp the step to (-1, 1), e.g. Math.min(Math.abs(step), 1) * Math.sign(step)
2. Split large movements into multiple moves of <= 1
3. Normalize the step by the intended traversal time before calling move

Example fix

// before
cursor.move(delta * speed); // may exceed 1
// after
const step = Math.max(-1, Math.min(1, delta * speed));
cursor.move(step);

const step = Math.max(-1, Math.min(1, rawStep));
if (Math.abs(rawStep) > 1) {
    console.warn("step clamped to", step);
}
cursor.move(step);

try {
    cursor.move(rawStep);
} catch (e) {
    if (e.message.includes("step size should be less than 1")) {
        let remaining = Math.sign(rawStep);
        while (Math.abs(remaining) > 0) {
            const s = Math.max(-1, Math.min(1, rawStep));
            cursor.move(s);
            break;
        }
    }
}

When it happens

Trigger: Calling pathCursor.move(step) with Math.abs(step) > 1, e.g. move(1.5) or move(-2), directly or indirectly via moveAhead/moveBack with a too-large delta.

Common situations: Computing a step from elapsed time without clamping (large frame delta); passing a normalized speed times a too-large factor; misunderstanding that step is a fraction of the segment, not distance.

Related errors

• Invalid property (${name}) in property path (${targetPropert
• Invalid property (${this._targetPath}) in property path (${t
• Invalid or empty skeleton provided
• Sample2DRgbaToRef: widthPx and heightPx must be positive.
• At least one mesh is needed to create the nav mesh.

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