Foundry Debugging - Fix Common Errors That Break Your Deploy

Debugging smart contracts is like debugging any other software, except when it breaks in production, you can't just restart the process. That failed transaction is stuck on the blockchain forever, mocking your "thoroughly tested" code. Foundry actually gives you tools to figure out what went wrong, but you need to know which buttons to push.

Common Production Failures

Gas Estimation Failures: Your deploy script worked fine on your local Anvil node but fails when you try to deploy to mainnet. This usually means your contract hit a gas limit that doesn't exist locally, or you're trying to deploy during a gas spike and your estimate is way off.

Revert Without Reason: The transaction reverted but there's no error message. This happens when you use require() without a message, or when the revert happens in assembly code. Foundry's traces can show you exactly where it died.

Constructor Arguments Mismatch: You copied the constructor arguments from your test but forgot that production uses different addresses, or you encoded the arguments wrong and your contract deployed with garbage data.

The Foundry Debugging Arsenal

Forge Test with Verbosity: When a test fails, run it with -vvvv to get full traces. This shows every internal call and state change, which is usually enough to spot the problem.

forge test --match-test testFailingFunction -vvvv

Call Traces: These show the exact execution path of a failed transaction. You can see which function called which, where it reverted, and what the state looked like at each step. Way more useful than Etherscan's basic transaction info.

Interactive Debugger: For complex failures, you can step through the transaction line by line. It's slow but thorough - think gdb for smart contracts.

forge test --match-test testComplexFailure --debug

Real Debugging Workflow

When something breaks, here's the process that actually works:

1. Reproduce Locally: Fork the production network state and run your failing transaction locally. This gives you full debugging access to a production-identical environment.

## Fork mainnet and replay the exact failure
forge test --fork-url $MAINNET_RPC --match-test testFailingFunction -vvvv

2. Add Traces: Run the failing test with maximum verbosity to see the full call stack. Look for the deepest function call that reverted.

3. Check State: Use Cast to query the current state of contracts involved in the failure. Often the issue is that some prerequisite wasn't met.

## Check contract state at the time of failure
cast storage $CONTRACT_ADDRESS $SLOT_NUMBER --rpc-url $MAINNET_RPC --block $FAILURE_BLOCK

4. Isolate the Problem: Write a minimal test that reproduces just the failing part. Strip away everything else until you have the simplest possible failure case.

The key insight is that most "mysterious" failures have simple explanations - wrong addresses, insufficient approvals, timing assumptions that don't hold on mainnet, or edge cases your tests didn't cover.

Why This Matters More Than You Think

Production debugging skills separate developers who ship reliably from those who ship hope. When your deployment fails at 2am and the team is waiting for a fix, knowing how to quickly isolate and debug the problem is worth more than any framework knowledge.

Foundry's debugging tools are powerful, but they're not intuitive if you're coming from JavaScript debugging. The investment in learning them pays off every time you avoid a multi-hour debugging session or catch a bug before it hits mainnet.

The basic traces and debugger handle most problems, but some issues need more specialized approaches. These are the techniques that separate developers who can ship under pressure from those who panic when weird stuff happens.

Forking for Perfect Reproduction

The most powerful debugging technique is forking the exact network state where your problem occurred. This gives you a local environment that matches production perfectly, including all the external contract states and permissions.

## Fork at specific block to reproduce timing-sensitive bugs
forge test --fork-url $MAINNET_RPC --fork-block-number 18500000

This is critical for debugging issues that involve external contracts, oracles, or time-sensitive operations. Your local tests might pass because they use mock contracts, but the real contracts have different behavior.

State Debugging: Once you're forked, you can inspect any contract state on the network. Use Cast to read storage slots, check balances, and verify that all preconditions are actually met.

Fuzzing Failures and Edge Cases

When your fuzz tests find a failure, the error message shows the exact input that broke your code. This input isn't random - it's designed to find edge cases you missed.

Reproduce the Fuzzing Input:

forge test --match-test fuzzTest --fuzz-seed 12345

Run the same seed to get reproducible failures. Then write a unit test with the exact failing input to understand why it breaks your assumptions.

Coverage-Guided Fuzzing: Foundry v1.3.0 added coverage-guided fuzzing that's much better at finding weird edge cases. When it finds a failure, the input is probably hitting a code path you've never tested manually.

Debugging Gas Issues

Gas failures aren't always about hitting limits - sometimes they indicate deeper algorithmic problems.

Gas Profiling by Function:

forge test --gas-report --match-test expensiveTest

This shows per-function gas usage. If one function is using way more gas than expected, you probably have an algorithmic issue (like an O(n²) operation) rather than a simple "increase gas limit" problem.

Memory vs Storage Access: Reading from storage costs 2,100 gas per slot, reading from memory costs 3 gas. If your gas usage is spiking unexpectedly, you might be hitting storage when you meant to hit memory.

Invariant Testing Failures

Invariant tests are the most sophisticated debugging challenge. When they fail, they've found a sequence of function calls that breaks a property you thought was always true.

Understanding the Attack Sequence: The test output shows exactly which functions were called in what order. This sequence represents a real attack vector or edge case that you need to handle.

State Transition Debugging: Add logging to your invariant tests to see how state changes throughout the attack sequence. Often the issue is that some intermediate state allows operations that should be forbidden.

function invariant_totalSupplyEqualsBalances() public {
    uint256 totalSupply = token.totalSupply();
    uint256 sumBalances = 0;
    
    // Debug: log current state
    console.log("Total supply:", totalSupply);
    console.log("Sum balances:", sumBalances);
    
    assertEq(totalSupply, sumBalances);
}

Production Incident Response

When something breaks in production and users are affected, you need a systematic approach to quickly identify and fix the issue.

Transaction Forensics: For a failed production transaction, get the full trace using the transaction hash:

cast run 0x[tx-hash] --debug

This shows exactly what happened, including all internal calls and state changes. Much more detailed than Etherscan.

State Verification: Check that all external dependencies are in expected states. Often production failures are caused by external contracts being upgraded, paused, or having different permissions than expected.

Minimal Reproduction: Once you understand the failure, create the smallest possible test that reproduces it. This makes it easy to verify that your fix actually works.

When Foundry Debugging Hits Limits

Some issues require tools beyond Foundry:

Assembly Debugging: For inline assembly or low-level issues, you might need to examine the actual EVM bytecode. The EVM debugger can step through individual opcodes.

Cross-Chain Issues: If your contract interacts with multiple chains, you need to fork multiple networks simultaneously, which gets complex. Consider using Tenderly or similar tools for these scenarios.

MEV-Related Failures: If your transaction is being front-run or sandwich attacked, the issue might not be in your code at all. These require understanding mempool dynamics and transaction ordering.

The key insight is that effective debugging is about quickly eliminating possibilities. Start with the most likely causes (wrong addresses, insufficient permissions, gas issues) before diving into complex edge cases. Most production failures have simple explanations once you know where to look.