Diagnosing a TON cell overflow with room left for bits
A serializer appends four child references and then fails while writing a fifth. Counting the body’s data bytes misses the independent reference budget of a TON cell.
Measure both budgets in the builder
The example uses an ordinary cell and a single leaf object in @ton/core. Reusing that leaf four times consumes four reference positions. After writing a 3-bit integer the builder still has 1,020 bits available but no free references. Testing only availableBits would allow an invalid append.
import { beginCell } from "@ton/core";
const leaf = beginCell().storeUint(1, 1).endCell();
const b = beginCell().storeUint(7, 3);
for (let i = 0; i < 4; i++) b.storeRef(leaf);
console.log(b.availableBits, b.availableRefs);
Choose a layout the receiver understands
If you control the schema, place several children under a nested cell and make the reader traverse that reference. Test with both empty and full child sets. For an existing TL-B schema, follow its specified nesting and inline/reference selectors. Moving a field into a new cell changes the serialized representation, so it can invalidate signatures or addresses derived from the previous layout.