The target may be missing and you must still return a position (where it would be inserted), as in Search Insert Position (LC 35), not -1.

The sorted values fill a grid whose rows continue one another, as in Search a 2D Matrix (LC 74): the positions are cells, so each mid must first be turned into a row and a column.

nums is sorted, so one comparison of nums[mid] with target tells you which half can still hold it: return mid on a match, otherwise drop mid and the wrong half with lo = mid + 1 or hi = mid - 1. Every index outside [lo, hi] has been ruled out, so once lo > hi nothing is left to check and -1 is the right answer. The trap is mixing styles: the closed range [lo, hi] needs while lo <= hi together with both mid + 1 and mid - 1; writing hi = mid, as a boundary search does, loops forever once lo == hi and nums[mid] is too big.

If target is in nums, its index is always inside [lo, hi].

candidate domain ➔ check midpoint == target ➔ early return

Writing hi = mid in the closed-range loop

The range [lo, hi] is closed, so nums[mid] has already been checked. When lo == hi and nums[mid] is larger than target, hi = mid leaves hi where it was. The range never gets smaller, so the loop never ends. hi = mid belongs to the boundary search, which loops while lo < hi.

Starting hi at len(nums) instead of len(nums) - 1

The closed range [lo, hi] reads nums[hi] when lo reaches it. len(nums) is one past the last index. When target is larger than every value, lo climbs to len(nums). Then nums[mid] is nums[len(nums)], and Python raises an IndexError.

Looping while lo < hi in the closed range

When lo == hi, one candidate is still left, and it has not been checked. while lo < hi stops before checking it. So a target that sits at that last index is reported as missing, and the function returns -1.

Writing (lo + hi) / 2 in Java or C++

In Java and C++, an int holds values up to 231 - 1. When lo and hi are both large, lo + hi is larger than that limit. In Java, the sum wraps around to a negative number, so mid is a negative index. In C++, an int that overflows is undefined behaviour. lo + (hi - lo) / 2 never computes a value larger than hi. Python integers have no size limit, so both forms work in Python.

A matrix is sorted along each row and every row starts after the previous row ends, so read row by row it is one sorted list, and you must find a value in log time.

If target is in matrix, its flat index is inside [lo, hi], and flat index mid is the cell matrix[mid // n][mid % n].

Because every row starts after the previous row ends, reading matrix row by row gives one sorted list of m * n values, so run Exact Match on that list's positions without building it: lo, hi = 0, m * n - 1, and turn each mid into a cell with row, col = divmod(mid, n). This is correct because position mid has exactly mid // n full rows before it and sits mid % n cells into its own row, so matrix[row][col] is the value the flat list would hold there, and each comparison of val with target drops mid and the half that cannot hold it. The trap is the divisor: it is n, the number of columns (the length of one row), not m. divmod(mid, m) still works on a square matrix, so the bug hides until a non-square one, where it reads the wrong cell or asks for a row that does not exist.

Writing divmod(mid, m) instead of divmod(mid, n)

Each row holds n cells, where n is the number of columns. So flat index mid is in row mid // n, at column mid % n. On a 3 x 4 matrix, flat index 5 is matrix[1][1]. divmod(5, 3) gives (1, 2) and reads matrix[1][2] instead. For target = 60, mid reaches 10, and divmod(10, 3) asks for row 3, which does not exist. A square matrix has m == n, so it hides this mistake.

Starting hi at m * n instead of m * n - 1

The last flat index is m * n - 1. The closed range [lo, hi] reads the cell at hi when lo reaches it. When target is larger than every value, mid reaches m * n. divmod(m * n, n) asks for row m, which does not exist, so Python raises an IndexError.

Picking the row with a separate binary search first

A search down the first column can pick the row, and a second search can look inside that row. This also runs in O(log(m * n)) time. But picking the row is a last-True search. It looks for the last row whose first value is at most target. That search is the Upper Bound card, and it has its own off-by-one risk. For example, a target below matrix[0][0] has no row at all. One search on the flat index has no row step to get wrong.

Walking from the top-right corner

The corner walk starts at the top-right cell. Each comparison drops one row or one column. It is correct, but it takes up to m + n steps. The problem asks for O(log(m * n)) time, which only the binary search meets.

Rows and columns are each sorted, but a row can start below the end of the row above, as in Search a 2D Matrix II (LC 240): read row by row it is not one sorted list, so there is no flat index to binary search.

You need the k-th smallest value, not whether one value is present, and only the rows and columns are sorted, as in Kth Smallest Element in a Sorted Matrix (LC 378).

Search a 2D Matrix