Diagnosing and Fixing Range Check Built‑in Errors in Cairo 2.0 Contracts

Recognizable Condition

During compilation or execution you see one of these messages:

• builtin not found: range_check – compile‑time error.
• range_check failed – runtime assert that stops the transaction.
• resource exhausted: range_check – the builtin was called more times than the available budget.

These symptoms point to an issue with the range_check builtin, a core Cairo feature that guarantees all 252‑bit arithmetic stays within the Stark Net field.

Common Causes

Cause	Typical Symptom
Missing builtin in cairo.toml	"builtin not found" at compile time.
Header missing #[builtin]	Silent gas mis‑estimation or wrong runtime behavior.
Out‑of‑range value passed to a builtin call	"range_check failed" during execution.
Exceeding the builtin resource budget	"resource exhausted" error after many calls.
Compiler auto‑add disabled in newer releases	Builtin not present even if you rely on templates.

Diagnostic Table

Match the symptom to the likely cause and follow the ordered checks below.

1. Verify Cairo Version

# Run on the machine that builds the contract
cairo-lang --version
# Expected output: 2.0.x (e.g., 2.0.0)

Range_check support is stable in 2.0.x. If you see 2.1.x or later, consult the release notes for changes.

2. Check Compiler Configuration

# Open your project’s cairo.toml
cat cairo.toml

# Look for the builtins list
[compiler]
builtins = ["pedersen", "range_check", "bitwise"]

Ensure range_check is listed. If absent, add it and re‑compile.

3. Inspect Contract Header

# Example of a correct header
#[starknet::contract]
#[builtin("range_check")]
mod my_contract {
    // contract code
}

The #[builtin("range_check")] attribute tells the compiler to include the builtin in the program header. Without it, the runtime won’t expose the builtin, leading to silent failures.

4. Compile with Builtin Visibility

# Show which builtins are compiled into the artifact
cairo-compile --show-builtin my_contract.cairo
# Verify that "range_check" appears in the output list.

If it’s missing, the header or config is wrong.

5. Deploy and Observe Runtime Logs

# Deploy to a testnet
starknet deploy --network goerli --contract my_contract.json

# Run a transaction that triggers the builtin
starknet invoke --network goerli --address  --entrypoint my_entrypoint --inputs 123456

# Check the transaction receipt for "range_check failed" or "resource exhausted".

Runtime errors usually surface as transaction reverts with the corresponding message.

Ordered Checks and Fixes

1. Confirm version – If you’re on 2.1.x or newer, read the migration guide for range_check changes.
2. Update cairo.toml – Add range_check to builtins. Commit and re‑compile.
3. Add header attribute – Insert #[builtin("range_check")] into each contract module that needs it.
4. Validate compile output – Run cairo-compile --show-builtin to ensure inclusion.
5. Test with in‑range values – Use values < 2252 to confirm the builtin passes.
6. Test with out‑of‑range values – Intentionally overflow to verify that the assert triggers and you see “range_check failed”.
   • If the transaction still succeeds, you may have disabled the builtin in the header.
7. Monitor resource usage – Each call consumes one unit of the range_check budget. For loops or repeated calls, ensure you stay within the limit. Use starknet-compile --show-builtins to see the estimated cost.
8. Adjust logic or batch calls – If you hit the budget, refactor to reduce builtin invocations or split the logic into multiple transactions.

Escalation Criteria

• After steps 1‑4, the error persists – contact the Cairo core team or open an issue on the official GitHub repository with the compiler output.
• Runtime logs show “resource exhausted” repeatedly – request a review of the transaction size or consult StarkNet DAO for potential resource limits.
• You encounter a different error message that mentions builtin but not range_check – verify that no other builtin is mis‑configured.

Limitations and Practical Checks

• The range_check builtin’s cost is fixed per call; however, the exact gas cost can vary between Cairo releases. Always re‑measure after an upgrade.
• Large numeric literals (> 2252−1) will trigger runtime asserts regardless of compile‑time configuration; sanitize inputs early.
• StarkNet’s default runtime does not expose builtins unless declared; deploying to a custom runtime may hide the error until execution.

Practical verification: after applying the fixes, run a unit test that passes a large but valid value (e.g., 2**251) and confirm the transaction succeeds. Then run a test that passes 2**252 and confirm the revert message is "range_check failed".

Conclusion

Range_check errors are usually a symptom of a missing or mis‑configured builtin. By following the ordered checks—verifying version, compiler config, contract header, compile output, and runtime logs—you can quickly pinpoint the issue and apply the appropriate fix. When the problem persists beyond these steps, escalating to the Cairo community or the StarkNet DAO is the next prudent action.