/docs/troubleshooting

Troubleshooting & FAQ.

Rugproof is designed to work out-of-the-box with zero configuration. When something looks off, it's usually one of these.

“It returned mock / stub data”

Any MCP result tagged "stub": true (or __stub / __reason) means a live integration wasn't available and a labeled sample was used instead. Causes & fixes:

You see	Why	Fix
block-explorer mock	no `ETHERSCAN_API_KEY`	Export an Etherscan API key (one key covers all Etherscan v2 chains).
slither-runner sample	Slither not on PATH	`pip install slither-analyzer`, or set `SLITHER_PATH`.
mythril-runner sample	Mythril not on PATH	`pip install mythril`, or set `MYTHRIL_PATH`.
forge-runner mock gas/coverage	Foundry not installed or build failed	Install Foundry; ensure `forge build` passes first.
tenderly stub	no `TENDERLY_*` creds	Set `TENDERLY_ACCESS_KEY`/`ACCOUNT`/`PROJECT`.

This is intentional — the plugin never hard-fails on a missing key or tool. To force stubs everywhere (CI, air-gapped), set RUGPROOF_OFFLINE=1.

“`/audit` found nothing”

Check your include/exclude globs — the target may be excluded (e.g. files matching **/*.t.sol or lib/** are skipped by default).
A clean contract legitimately returns zero findings — Rugproof won't manufacture issues to look thorough.
Lower the bar with /audit-deep or /audit-strict for a multi-pass review.

“The Hardhat MCP hangs / times out”

Fixed in v0.2.0: the runner uses npx --no-install with closed stdin and a timeout, so it fails fast outside a Hardhat project instead of waiting on an install prompt. Tune the cap with RUGPROOF_HH_TIMEOUT_MS.

“An anvil fork didn't come up”

The anvil MCP now polls the RPC for readiness and errors clearly if it can't reach eth_blockNumber within 20s. Check that anvil is on PATH and the upstream fork RPC is reachable.

“MCP server not connecting”

Build the servers: cd mcp && npm install && npm run build.
Smoke-test all of them: node scripts/dist/test-mcp.js (expect 11/11).
plugin.json points each server at mcp/<name>-mcp/dist/index.js — make sure dist/ exists.

Rate limits

The history servers (c4/sherlock) and explorer calls retry with exponential backoff and honour Retry-After. Set GITHUB_TOKEN to raise the GitHub search rate limit.