{"record":{"id":"e0a95d8eefb56472","repo":"invoke-ai/InvokeAI","slug":"cfg-scale-start-step-cfg-scale-start-step-must","errorCode":null,"errorMessage":"cfg_scale_start_step ({cfg_scale_start_step}) must be before cfg_scale_end_step ({cfg_scale_end_step}).","messagePattern":"cfg_scale_start_step \\((.+?)\\) must be before cfg_scale_end_step \\((.+?)\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/app/invocations/flux_denoise.py","lineNumber":657,"sourceCode":"        else:\n            raise ValueError(f\"Unsupported cfg_scale type: {type(cfg_scale)}\")\n        assert len(cfg_scale_list) == num_steps\n\n        # Handle negative indices for cfg_scale_start_step and cfg_scale_end_step.\n        start_step_index = cfg_scale_start_step\n        if start_step_index < 0:\n            start_step_index = num_steps + start_step_index\n        end_step_index = cfg_scale_end_step\n        if end_step_index < 0:\n            end_step_index = num_steps + end_step_index\n\n        # Validate the start and end step indices.\n        if not (0 <= start_step_index < num_steps):\n            raise ValueError(f\"Invalid cfg_scale_start_step. Out of range: {cfg_scale_start_step}.\")\n        if not (0 <= end_step_index < num_steps):\n            raise ValueError(f\"Invalid cfg_scale_end_step. Out of range: {cfg_scale_end_step}.\")\n        if start_step_index > end_step_index:\n            raise ValueError(\n                f\"cfg_scale_start_step ({cfg_scale_start_step}) must be before cfg_scale_end_step \"\n                + f\"({cfg_scale_end_step}).\"\n            )\n\n        # Set values outside the start and end step indices to 1.0. This is equivalent to disabling cfg_scale for those\n        # steps.\n        clipped_cfg_scale = [1.0] * num_steps\n        clipped_cfg_scale[start_step_index : end_step_index + 1] = cfg_scale_list[start_step_index : end_step_index + 1]\n\n        return clipped_cfg_scale\n\n    def _prep_inpaint_mask(self, context: InvocationContext, latents: torch.Tensor) -> torch.Tensor | None:\n        \"\"\"Prepare the inpaint mask.\n\n        - Loads the mask\n        - Resizes if necessary\n        - Casts to same device/dtype as latents\n        - Expands mask to the same shape as latents so that they line up after 'packing'","sourceCodeStart":639,"sourceCodeEnd":675,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/app/invocations/flux_denoise.py#L639-L675","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"// before\nprep_cfg_scale(cfg_scale_start_step=5, cfg_scale_end_step=2) // inverted\n// after\nprep_cfg_scale(cfg_scale_start_step=2, cfg_scale_end_step=5)","handlingStrategy":"validation","validationCode":"start_idx = cfg_scale_start_step + num_steps if cfg_scale_start_step < 0 else cfg_scale_start_step\nend_idx = cfg_scale_end_step + num_steps if cfg_scale_end_step < 0 else cfg_scale_end_step\nif start_idx > end_idx:\n    cfg_scale_start_step, cfg_scale_end_step = cfg_scale_end_step, cfg_scale_start_step","typeGuard":"def cfg_window_ordered(start: int, end: int, num_steps: int) -> bool:\n    rs = start + num_steps if start < 0 else start\n    re = end + num_steps if end < 0 else end\n    return 0 <= rs <= re < num_steps","tryCatchPattern":"try:\n    cfg_list = denoise.prep_cfg_scale(cfg_scale, num_steps, cfg_scale_start_step=s, cfg_scale_end_step=e)\nexcept ValueError as e:\n    if 'must be before cfg_scale_end_step' in str(e):\n        s, e = e, s\n        cfg_list = denoise.prep_cfg_scale(cfg_scale, num_steps, cfg_scale_start_step=s, cfg_scale_end_step=e)\n    else:\n        raise","preventionTips":["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"],"tags":["cfg-scale","range-error","flux","validation"],"backgroundTag":"invalid-argument-range","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}