{"record":{"id":"d94c5785e59e22d0","repo":"PHPOffice/PhpSpreadsheet","slug":"num-d94c57","errorCode":"#NUM!","errorMessage":"#NUM!","messagePattern":"#NUM!","errorType":"error_code","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"src/PhpSpreadsheet/Calculation/Engineering/BitWise.php","lineNumber":204,"sourceCode":"        if ($result > 2 ** 48 - 1) { // possible because shiftAmount can be negative\n            return ExcelError::NAN();\n        }\n\n        return $result;\n    }\n\n    /**\n     * Validate arguments passed to the bitwise functions.\n     */\n    private static function validateBitwiseArgument(mixed $value): float\n    {\n        $value = self::nullFalseTrueToNumber($value);\n\n        if (is_numeric($value)) {\n            $value = (float) $value;\n            if ($value == floor($value)) {\n                if (($value > 2 ** 48 - 1) || ($value < 0)) {\n                    throw new Exception(ExcelError::NAN());\n                }\n\n                return floor($value);\n            }\n\n            throw new Exception(ExcelError::NAN());\n        }\n\n        throw new Exception(ExcelError::VALUE());\n    }\n\n    /**\n     * Validate arguments passed to the bitwise functions.\n     */\n    private static function validateShiftAmount(mixed $value): int\n    {\n        $value = self::nullFalseTrueToNumber($value);\n","sourceCodeStart":186,"sourceCodeEnd":222,"githubUrl":"https://github.com/PHPOffice/PhpSpreadsheet/blob/65b080eef4d9fd11a5796135ab145883e5c3d6a6/src/PhpSpreadsheet/Calculation/Engineering/BitWise.php#L186-L222","documentation":"#NUM! from the shared bitwise argument validator used by BITAND, BITOR, BITXOR, BITLSHIFT and BITRSHIFT. Excel limits bitwise operands to non-negative integers up to 2^48-1 (281,474,976,710,655); validateBitwiseArgument() throws Calculation\\Exception('#NUM!') for any integer outside 0..2^48-1, and the public wrappers return it as the '#NUM!' result string.","triggerScenarios":"=BITAND(281474976710656, 1), =BITXOR(-1, 2), =BITLSHIFT(300000000000000, 8); PHP calls like BitWise::BITAND(-5, 3); values produced by float arithmetic that exceed the 48-bit ceiling after the (float) cast.","commonSituations":"Passing negative numbers expecting two's-complement behaviour (Excel bitwise functions reject negatives outright); feeding 64-bit IDs, bitmasks from GMP/BCMath code, or float-computed values straight into bitwise formulas; migrating PHP ~ or & expressions to Excel equivalents.","solutions":["Clamp or reject inputs to the range 0..281474976710655 before calling the bitwise functions.","For negative or >48-bit integers, compute the result in PHP with GMP/BCMath and write the value instead of the formula.","Remember BITLSHIFT/BITRSHIFT also return #NUM! when the shifted result exceeds 2^48-1, not just the input.","Check returned values for the '#NUM!' string when inputs are dynamic."],"exampleFix":"// before\n$result = BitWise::BITAND($userMask, $flags); // $userMask = -1 -> '#NUM!'\n\n// after\n$result = ($userMask >= 0 && $userMask <= 2 ** 48 - 1)\n    ? BitWise::BITAND($userMask, $flags)\n    : gmp_intval(gmp_and(gmp_init($userMask), gmp_init($flags)));","handlingStrategy":"validation","validationCode":"const BITWISE_MAX = 281474976710655; // 2**48 - 1\nif (!is_int($n) || $n < 0 || $n > BITWISE_MAX) {\n    throw new \\InvalidArgumentException('bitwise operand must be an integer in 0..2^48-1');\n}\n$result = BitWise::BITAND($n, $mask);","typeGuard":"/** Excel bitwise operands: non-negative integers up to 2^48-1. */\nfunction isValidBitwiseOperand(mixed $v): bool\n{\n    return is_numeric($v)\n        && (float) $v == floor((float) $v)\n        && (float) $v >= 0\n        && (float) $v <= 2 ** 48 - 1;\n}","tryCatchPattern":null,"preventionTips":["Excel bitwise functions have no negative-number support - mask or reject negatives first.","For >48-bit work use PHP's GMP extension and write values, not formulas.","BITLSHIFT results above 2^48-1 also yield '#NUM!' even with valid inputs."],"tags":["phpspreadsheet","excel-formula","bitwise","integer-overflow","argument-range"],"backgroundTag":"excel-num-error","analyzedSha":"65b080eef4d9fd11a5796135ab145883e5c3d6a6","analyzedAt":"2026-08-17T05:40:41.646Z","schemaVersion":2},"datasetVersion":"2026-08-17T09:17:11.063Z"}