invoke-ai/InvokeAI · error · ValueError

cfg_scale_start_step ({cfg_scale_start_step}) must be before

Q: What causes "cfg_scale_start_step ({cfg_scale_start_step}) must be before cfg_scale_end_step ({cfg_scale_end_step})." in invoke-ai/InvokeAI?

Ensure start <= end before calling; swap the values if they are reversed.

Error message

cfg_scale_start_step ({cfg_scale_start_step}) must be before cfg_scale_end_step ({cfg_scale_end_step}).

What it means

prep_cfg_scale requires the CFG schedule window to be ordered: the resolved start step index must not exceed the resolved end step index. An inverted window is meaningless (no steps would have CFG applied), so it raises a descriptive error including both original values.

Source

Thrown at invokeai/app/invocations/flux_denoise.py:657

        else:
            raise ValueError(f"Unsupported cfg_scale type: {type(cfg_scale)}")
        assert len(cfg_scale_list) == num_steps

        # Handle negative indices for cfg_scale_start_step and cfg_scale_end_step.
        start_step_index = cfg_scale_start_step
        if start_step_index < 0:
            start_step_index = num_steps + start_step_index
        end_step_index = cfg_scale_end_step
        if end_step_index < 0:
            end_step_index = num_steps + end_step_index

        # Validate the start and end step indices.
        if not (0 <= start_step_index < num_steps):
            raise ValueError(f"Invalid cfg_scale_start_step. Out of range: {cfg_scale_start_step}.")
        if not (0 <= end_step_index < num_steps):
            raise ValueError(f"Invalid cfg_scale_end_step. Out of range: {cfg_scale_end_step}.")
        if start_step_index > end_step_index:
            raise ValueError(
                f"cfg_scale_start_step ({cfg_scale_start_step}) must be before cfg_scale_end_step "
                + f"({cfg_scale_end_step})."
            )

        # Set values outside the start and end step indices to 1.0. This is equivalent to disabling cfg_scale for those
        # steps.
        clipped_cfg_scale = [1.0] * num_steps
        clipped_cfg_scale[start_step_index : end_step_index + 1] = cfg_scale_list[start_step_index : end_step_index + 1]

        return clipped_cfg_scale

    def _prep_inpaint_mask(self, context: InvocationContext, latents: torch.Tensor) -> torch.Tensor | None:
        """Prepare the inpaint mask.

        - Loads the mask
        - Resizes if necessary
        - Casts to same device/dtype as latents
        - Expands mask to the same shape as latents so that they line up after 'packing'

View on GitHub (pinned to 0b6a024f2f)

Solutions

Ensure start <= end before calling; swap the values if they are reversed.
If using negative indices, remember both are resolved relative to num_steps first; verify resolved indices satisfy start <= end.
Normalize: if (start > end) { [start, end] = [end, start]; } before the call.

Example fix

// before
prep_cfg_scale(cfg_scale_start_step=5, cfg_scale_end_step=2) // inverted
// after
prep_cfg_scale(cfg_scale_start_step=2, cfg_scale_end_step=5)

Defensive patterns

Strategy: validation

Validate before calling

start_idx = cfg_scale_start_step + num_steps if cfg_scale_start_step < 0 else cfg_scale_start_step
end_idx = cfg_scale_end_step + num_steps if cfg_scale_end_step < 0 else cfg_scale_end_step
if start_idx > end_idx:
    cfg_scale_start_step, cfg_scale_end_step = cfg_scale_end_step, cfg_scale_start_step

Type guard

def cfg_window_ordered(start: int, end: int, num_steps: int) -> bool:
    rs = start + num_steps if start < 0 else start
    re = end + num_steps if end < 0 else end
    return 0 <= rs <= re < num_steps

Try / catch

try:
    cfg_list = denoise.prep_cfg_scale(cfg_scale, num_steps, cfg_scale_start_step=s, cfg_scale_end_step=e)
except ValueError as e:
    if 'must be before cfg_scale_end_step' in str(e):
        s, e = e, s
        cfg_list = denoise.prep_cfg_scale(cfg_scale, num_steps, cfg_scale_start_step=s, cfg_scale_end_step=e)
    else:
        raise

Prevention

Normalize the window (swap if reversed) before invoking
Test CFG-schedule nodes with both slider orders
Document that negative indices resolve before the ordering check

When it happens

Trigger: Calling prep_cfg_scale where cfg_scale_start_step > cfg_scale_end_step after negative-index resolution (e.g. start=5, end=2, or start=-1 with end=-3).

Common situations: Swapping the start/end sliders by accident; passing defaults where the start default is larger than the end default; programmatically computing indices with subtraction that goes negative in the wrong order.

Related errors

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