{"record":{"id":"7fc713e6d743b4a0","repo":"keras-team/keras","slug":"received-an-invalid-value-for-argument-num-heads","errorCode":null,"errorMessage":"Received an invalid value for argument `num_heads`, expected a positive integer. Received: num_heads={num_heads}","messagePattern":"Received an invalid value for argument `num_heads`, expected a positive integer\\. Received: num_heads=(.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"keras/src/layers/attention/multi_head_attention.py","lineNumber":138,"sourceCode":"        dropout=0.0,\n        use_bias=True,\n        output_shape=None,\n        attention_axes=None,\n        sliding_window=None,\n        flash_attention=None,\n        kernel_initializer=\"glorot_uniform\",\n        bias_initializer=\"zeros\",\n        kernel_regularizer=None,\n        bias_regularizer=None,\n        activity_regularizer=None,\n        kernel_constraint=None,\n        bias_constraint=None,\n        use_gate=False,\n        seed=None,\n        **kwargs,\n    ):\n        if not isinstance(num_heads, int) or num_heads <= 0:\n            raise ValueError(\n                \"Received an invalid value for argument `num_heads`, \"\n                f\"expected a positive integer. Received: num_heads={num_heads}\"\n            )\n        if not isinstance(key_dim, int) or key_dim <= 0:\n            raise ValueError(\n                \"Received an invalid value for argument `key_dim`, expected \"\n                f\"a positive integer. Received: key_dim={key_dim}\"\n            )\n        if value_dim is not None and (\n            not isinstance(value_dim, int) or value_dim <= 0\n        ):\n            raise ValueError(\n                \"Received an invalid value for argument `value_dim`, \"\n                \"expected a positive integer or `None`. Received: \"\n                f\"value_dim={value_dim}\"\n            )\n        super().__init__(**kwargs)\n        self.supports_masking = True","sourceCodeStart":120,"sourceCodeEnd":156,"githubUrl":"https://github.com/keras-team/keras/blob/7a34a03db60bf60042242d6a556fc3be119046a5/keras/src/layers/attention/multi_head_attention.py#L120-L156","documentation":"MultiHeadAttention.__init__ validates num_heads up front: it must be a Python int (bools, floats, numpy scalars and None all fail the checks) and strictly positive, else ValueError. The same validation follows for key_dim and related args. The check exists because the head count splits the feature axis, which is impossible for zero, negative, or non-integer counts.","triggerScenarios":"MultiHeadAttention(num_heads=0), num_heads=-2, num_heads=8.0, num_heads=np.int64(8) (a numpy scalar is not a Python int), or num_heads coming out of a config as None.","commonSituations":"Hyperparameter sweeps that hit zero; YAML or JSON configs parsed as floats (8.0); numpy ints passed straight from array-based configs; refactors that leave the argument unset.","solutions":["Pass a positive Python int: MultiHeadAttention(num_heads=8, key_dim=64).","Coerce config values at the boundary: num_heads = int(cfg['heads']) and assert num_heads > 0 before constructing.","Guard sweep search spaces to exclude non-positive head counts."],"exampleFix":"# before\nmha = MultiHeadAttention(num_heads=0, key_dim=64)  # -> ValueError\n\n# after\nheads = int(cfg.get('num_heads', 8))\nassert heads > 0\nmha = MultiHeadAttention(num_heads=heads, key_dim=64)","handlingStrategy":"type-guard","validationCode":"h = cfg.get('num_heads')\nassert isinstance(h, int) and not isinstance(h, bool) and h > 0, 'num_heads must be a positive int'","typeGuard":"def valid_num_heads(n) -> bool:\n    return isinstance(n, int) and not isinstance(n, bool) and n > 0","tryCatchPattern":null,"preventionTips":["Cast config values with int() at the boundary and assert positivity.","Exclude zero and negative head counts from hyperparameter search grids.","Watch for floats (8.0) and numpy scalars from parsed configs."],"tags":["keras","multi-head-attention","argument-validation","value-error"],"backgroundTag":"invalid-argument-value","analyzedSha":"7a34a03db60bf60042242d6a556fc3be119046a5","analyzedAt":"2026-08-25T21:25:25.994Z","schemaVersion":2},"datasetVersion":"2026-08-26T02:17:13.382Z"}