From 7e8827b1c5ec8a771d18e81bca607cd607df4ab3 Mon Sep 17 00:00:00 2001
From: 96e5 <128492257+96e5@users.noreply.github.com>
Date: Tue, 10 Feb 2026 10:17:37 +0100
Subject: [PATCH] docs: add troubleshooting note for forge invariants with
 --fork-url

Adds a short troubleshooting section about invariant runs stalling with --fork-url, with workarounds and a link to the upstream Foundry issue.
---
 src/pages/sdk/foundry/index.mdx | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/src/pages/sdk/foundry/index.mdx b/src/pages/sdk/foundry/index.mdx
index 885e99d..4ffdabf 100644
--- a/src/pages/sdk/foundry/index.mdx
+++ b/src/pages/sdk/foundry/index.mdx
@@ -301,4 +301,15 @@ The following flags are available for `cast` and `forge script` for Tempo-specif
 
 Ledger and Trezor wallets are not yet compatible with any `--tempo.*` option.
 
+## Troubleshooting
+
+### Invariant tests with `--fork-url`
+In some Foundry versions, invariant runs may stall when used with `--fork-url` / `--fork-block-number`.
+
+Workarounds:
+- Run invariants without forking, and use `--fork-url` only for non-invariant tests.
+- If you only need a quick sanity check, temporarily focus on non-invariant tests while forking.
+
+Upstream tracking: https://github.com/foundry-rs/foundry/issues/4656
+