invoke-ai/InvokeAI · error · ValueError

Begin step percent must be less than or equal to end step pe

Error message

Begin step percent must be less than or equal to end step percent

What it means

validate_begin_end_step enforces that a conditioning adapter's begin_step_percent is <= end_step_percent, i.e. the percent window must be ordered. An inverted window (start after end) is rejected with ValueError.

Source

Thrown at invokeai/app/invocations/util.py:14

from typing import Union


def validate_weights(weights: Union[float, list[float]]) -> None:
    """Validate that all control weights in the valid range"""
    to_validate = weights if isinstance(weights, list) else [weights]
    if any(i < -1 or i > 2 for i in to_validate):
        raise ValueError("Control weights must be within -1 to 2 range")


def validate_begin_end_step(begin_step_percent: float, end_step_percent: float) -> None:
    """Validate that begin_step_percent is less than or equal to end_step_percent"""
    if begin_step_percent > end_step_percent:
        raise ValueError("Begin step percent must be less than or equal to end step percent")

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Ensure begin_step_percent <= end_step_percent (e.g. begin=0.2, end=0.8)
2. Swap the two values if they were entered in the wrong order
3. Clamp with min/max when computing programmatically

Example fix

// before
validate_begin_end_step(0.8, 0.2)
// after
validate_begin_end_step(min(a, b), max(a, b))  # e.g. (0.2, 0.8)

if not (0.0 <= begin_step_percent <= end_step_percent <= 1.0):
    raise ValueError("require 0 <= begin <= end <= 1")

def is_valid_step_window(b: float, e: float) -> bool:
    return isinstance(b, float) and isinstance(e, float) and 0.0 <= b <= e <= 1.0

try:
    validate_begin_end_step_percent(begin, end)
except ValueError as e:
    if "Begin step percent" in str(e):
        begin, end = min(begin, end), max(begin, end)
    else:
        raise

When it happens

Trigger: Calling validate_begin_end_step_percent with begin_step_percent=0.8, end_step_percent=0.2 when configuring a ControlNet/IP-Adapter's step window.

Common situations: Swapping the two fields in a workflow node or UI; computing percentages dynamically and dividing by the wrong base; copying begin/end values into the wrong inputs.

Related errors

• denoising_start ({self.denoising_start}) must be less than d
• LoRA "{lora_key}" already applied to transformer.
• A saved workflow must be selected before executing call_save
• The selected saved workflow '${self.workflow_id}' could not
• Selected model provider '{model_config.provider_id}' does no

AI-assisted analysis of invoke-ai/InvokeAI@0b6a024f2f (2026-08-29). Data as JSON: /api/errors/773e88b84f44b3cb. Report an issue: GitHub.