{"record":{"id":"df866e056af893df","repo":"invoke-ai/InvokeAI","slug":"control-weights-must-be-within-1-to-2-range","errorCode":null,"errorMessage":"Control weights must be within -1 to 2 range","messagePattern":"Control weights must be within -1 to 2 range","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/app/invocations/util.py","lineNumber":8,"sourceCode":"from typing import Union\n\n\ndef validate_weights(weights: Union[float, list[float]]) -> None:\n    \"\"\"Validate that all control weights in the valid range\"\"\"\n    to_validate = weights if isinstance(weights, list) else [weights]\n    if any(i < -1 or i > 2 for i in to_validate):\n        raise ValueError(\"Control weights must be within -1 to 2 range\")\n\n\ndef validate_begin_end_step(begin_step_percent: float, end_step_percent: float) -> None:\n    \"\"\"Validate that begin_step_percent is less than or equal to end_step_percent\"\"\"\n    if begin_step_percent > end_step_percent:\n        raise ValueError(\"Begin step percent must be less than or equal to end step percent\")\n","sourceCodeStart":1,"sourceCodeEnd":15,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/app/invocations/util.py#L1-L15","documentation":"InvokeAI validates control (ControlNet) and IP-Adapter weights via validate_weights, requiring each weight to lie within [-1, 2]. Values outside that range would produce degenerate conditioning or are simply unsupported, so a ValueError is raised.","triggerScenarios":"Calling validate_control_weight or validate_ip_adapter_weight with weight=-1.5, 2.5, or a list containing any element outside [-1, 2]; e.g. controlnet weight field set to 3 in a workflow.","commonSituations":"Trying aggressive negative conditioning (< -1) to suppress a concept; typing 20 instead of 2.0; copying weights from other tools that allow a wider range.","solutions":["Clamp each weight into the [-1, 2] range (e.g. 2.0 instead of 3)","For lists, ensure every element is within range","If stronger effect is needed, stack multiple control adapters rather than exceeding the weight cap"],"exampleFix":"// before\nvalidate_ip_adapter_weight(2.5)\n// after\nvalidate_ip_adapter_weight(min(max(w, -1.0), 2.0) for each w)  # e.g. 2.0","handlingStrategy":"validation","validationCode":"def validate_weights_client(weights):\n    vals = weights if isinstance(weights, list) else [weights]\n    if any(w < -1 or w > 2 for w in vals):\n        raise ValueError(\"Control weights must be within -1 to 2 range\")\n    return weights","typeGuard":"def weights_in_range(weights) -> bool:\n    vals = weights if isinstance(weights, list) else [weights]\n    return all(isinstance(w, (int, float)) and -1 <= w <= 2 for w in vals)","tryCatchPattern":"try:\n    invocation.invoke(context)\nexcept ValueError as e:\n    if \"Control weights must be within -1 to 2 range\" in str(e):\n        invocation.control_weight = [min(max(w, -1.0), 2.0) for w in weights]\n        invocation.invoke(context)\n    else:\n        raise","preventionTips":["Clamp weights to [-1, 2] when computing them programmatically","For stronger effect, add another ControlNet unit instead of exceeding the cap","Sanitize values imported from other tools with different weight conventions"],"tags":["validation","invokeai","controlnet"],"backgroundTag":"parameter-value-out-of-range","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}