---
title: "Stop integer arithmetic from overflowing · Agent Wranglers"
url: https://agentwranglers.se/playbook/architecture/data-shapes/integer-overflow
updated: 2026-10-21
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Stop integer arithmetic from overflowing

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Data shapes](https://agentwranglers.se/playbook/architecture/data-shapes.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers). Updated 2026-10-21.

- ID: ARC-70
- Level: Required
- Chapter: [Data shapes](https://agentwranglers.se/playbook/architecture/data-shapes)
- Rule: Give every count, amount and size a type wide enough for its largest valid value. Arithmetic on values from outside fails with an error instead of wrapping around or losing digits.
- Risk: Data leaked or lost
- How: Fixed-size integers wrap silently in many languages, so a large total turns negative. JavaScript numbers lose exact digits above `Number.MAX_SAFE_INTEGER`, which is 2^53 - 1. Check outside numbers against a minimum and a maximum when you [parse input once at the boundary](https://agentwranglers.se/playbook/architecture/data-shapes/parse-at-the-boundary). Use checked operations, such as `Math.addExact` in Java or `checked_add` in Rust, or a big integer type such as `BigInt`. Money follows [hold money as integer minor units everywhere](https://agentwranglers.se/playbook/payments/amounts-and-orders/money-in-minor-units).
- Check: A test feeds each numeric input its maximum, its maximum plus one and a negative value. It expects the maximum to work and the other two to be refused with an error. Linters flag unchecked casts and arithmetic, such as Clippy `arithmetic_side_effects` and `cast_possible_truncation` for Rust, or `-ftrapv` and `-fsanitize=integer` for C.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### Java example

```java
// Bad: two large totals wrap around to a negative number
int total = basketTotal + shippingTotal;

// Good: throws ArithmeticException instead of wrapping
long total = Math.addExact(basketTotal, shippingTotal);
```

### TypeScript example

```ts
// Bad: above 2^53 - 1 the last digits are silently wrong
const ledgerTotal = rows.reduce((sum, row) => sum + row.amount, 0);

// Good: BigInt keeps every digit, and the input is checked first
if (!rows.every(row => Number.isSafeInteger(row.amount))) throw new AmountOutOfRange();
const ledgerTotal = rows.reduce((sum, row) => sum + BigInt(row.amount), 0n);
```

### Plain text example

```rust
// Good: checked_add returns None on overflow, so the error is explicit
let total = basket_total.checked_add(shipping_total).ok_or(Error::AmountOutOfRange)?;
```

## Sources

- [CWE-190 Integer Overflow or Wraparound](https://cwe.mitre.org/data/definitions/190.html)
- [ECMA-262 Number.MAX_SAFE_INTEGER](https://tc39.es/ecma262/#sec-number.max_safe_integer)

## Related rules

- [Parse input once at the boundary](https://agentwranglers.se/playbook/architecture/data-shapes/parse-at-the-boundary) in Architecture
- [Hold money as integer minor units everywhere](https://agentwranglers.se/playbook/payments/amounts-and-orders/money-in-minor-units) in Payments

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/architecture/data-shapes/integer-overflow">Agent Wranglers architecture playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Insert text literally when you replace](https://agentwranglers.se/playbook/architecture/data-shapes/literal-replacement)
- Next: [Keep equality and hashing in step](https://agentwranglers.se/playbook/architecture/data-shapes/equality-and-hash)
- [Data shapes](https://agentwranglers.se/playbook/architecture/data-shapes)