{"record":{"id":"c9536a9593d0d140","repo":"headroomlabs-ai/headroom","slug":"must-be-field-maximum","errorCode":null,"errorMessage":"must be <= {field.maximum}","messagePattern":"must be <= (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":422,"severity":"error","filePath":"headroom/settings_store.py","lineNumber":789,"sourceCode":"        if token in (\"0\", \"false\", \"no\", \"off\", \"\"):\n            return False\n        raise ValueError(f\"expected a boolean, got {value!r}\")\n    if field.type in (\"int\", \"float\"):\n        if isinstance(value, bool):  # bool is an int subclass — reject explicitly\n            raise ValueError(f\"expected a number, got {value!r}\")\n        number: int | float\n        if field.type == \"int\":\n            if isinstance(value, float) and not value.is_integer():\n                raise ValueError(f\"expected an integer, got {value!r}\")\n            number = int(value)\n        else:\n            number = float(value)\n            if not math.isfinite(number):\n                raise ValueError(f\"expected a finite number, got {value!r}\")\n        if field.minimum is not None and number < field.minimum:\n            raise ValueError(f\"must be >= {field.minimum}\")\n        if field.maximum is not None and number > field.maximum:\n            raise ValueError(f\"must be <= {field.maximum}\")\n        return number\n    if field.type == \"enum\":\n        token = str(value)\n        if token not in field.choices:\n            raise ValueError(f\"{token!r} not one of {list(field.choices)}\")\n        return token\n    if field.type == \"csv-list\":\n        tokens = value if isinstance(value, list | tuple) else str(value).split(\",\")\n        tokens = [str(token).strip() for token in tokens]\n        tokens = [token for token in tokens if token]\n        return \",\".join(tokens) if tokens else None\n    if field.type == \"header-map\":\n        if isinstance(value, dict):\n            parsed = value\n        else:\n            try:\n                parsed = json.loads(str(value))\n            except (ValueError, TypeError) as exc:","sourceCodeStart":771,"sourceCodeEnd":807,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/settings_store.py#L771-L807","documentation":"ValueError from _coerce in headroom/settings_store.py when a numeric field's coerced value exceeds the field's declared maximum (field.maximum, checked at line 789). The message states the exact ceiling; the error is reported per-field through SettingsValidationError.field_errors.","triggerScenarios":"save({'port': 70000}) for a port field with maximum=65535; raising max_tokens above the model's documented cap; percentage fields set to 150 when maximum=100.","commonSituations":"Users typing oversized numbers into unbounded inputs; migrating configs tuned for a bigger model/deployment; unit confusion (ms vs s) inflating a value past the cap.","solutions":["Lower the value to at most the maximum stated in the message.","Check for unit mismatch (seconds vs milliseconds) that inflated the number.","Read the field's help text via the settings registry if the cap seems arbitrary."],"exampleFix":"# before\nsave({'port': 70000})  # ValueError: must be <= 65535\n\n# after\nsave({'port': 65535})","handlingStrategy":"validation","validationCode":"from headroom.settings_store import _BY_KEY\n\ndef not_above_max(key: str, v: int | float) -> bool:\n    f = _BY_KEY.get(key)\n    return f is None or f.maximum is None or v <= f.maximum","typeGuard":null,"tryCatchPattern":"except SettingsValidationError as e:\n    for key, msg in e.field_errors.items():\n        if 'must be <=' in msg:\n            payload[key] = min(payload[key], _BY_KEY[key].maximum)\n    store.save(payload)","preventionTips":["Clamp values against field.maximum before saving.","Validate units at the edge of your system (UI/API) so caps are never approached by accident."],"tags":["settings","validation","range"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}