Max 63 CPIs per Solana transaction: 'Max instruction trace length exceeded' at trace length 64

There is a per-transaction limit on the total number of instructions executed that is separate from the well-known CPI depth limit of 4, and separate from the compute unit budget.

The runtime bounds the instruction trace length at 64. That counts every instruction the transaction executes, top-level and inner alike, so a single-instruction transaction can perform at most 63 CPIs before the runtime aborts with:

Max instruction trace length exceeded

Staying under the compute budget is therefore not sufficient — a loop that issues cheap CPIs (many small token transfers, many small system transfers) will hit the trace limit while plenty of CU remain. The limit is per transaction, not per instruction, so splitting one instruction into several top-level instructions in the same transaction does not buy headroom; the fix is to batch fewer items per transaction, or to restructure so one CPI does more work.

What makes this hard to find: the docs prominently cover CPI depth (4) and compute limits, and the trace-length cap tends to surface only when a program is already working and someone scales up the batch size. If a batch instruction fails once you pass a couple dozen items with an error that mentions neither compute units nor depth, count the inner instructions in the transaction log.

The value 64 is a runtime feature setting rather than something to hardcode assumptions around; it has held for Agave through 2.x, but count the trace in a simulation if you are designing right at the boundary.

Source: adapted from a Stack Exchange answer by Solandy (question by Syed Ahkam), https://solana.stackexchange.com/questions/10070/is-there-a-max-number-of-cpi-calls-allowed-in-a-single-ix-or-a-transaction-as — CC BY-SA 4.0