# Troubleshooting

**Last Updated:** 2026-01-31  
**Document Version:** 1.0  
**Status:** Active Documentation

---

This directory contains troubleshooting guides and FAQs.

## Documents

- **[TROUBLESHOOTING_FAQ.md](TROUBLESHOOTING_FAQ.md)** ⭐⭐⭐ - Common issues and solutions - **Start here for problems**
- **[RPC_NODES_BLOCK_PRODUCTION_FIX.md](RPC_NODES_BLOCK_PRODUCTION_FIX.md)** ⭐⭐ - RPC nodes not responding; **ping works but curl doesn’t** (use POST + JSON-RPC; see section “Ping works but curl to :8545 doesn’t?”)
- **[METAMASK_TROUBLESHOOTING_GUIDE.md](METAMASK_TROUBLESHOOTING_GUIDE.md)** ⭐⭐ - MetaMask on Chain 138 (RPC, tokens, swaps, XChain error)
- **[QBFT_TROUBLESHOOTING.md](QBFT_TROUBLESHOOTING.md)** ⭐⭐ - QBFT consensus troubleshooting

## Quick Reference

**Common Issues:**
1. Check TROUBLESHOOTING_FAQ.md for common problems
2. For consensus issues, see QBFT_TROUBLESHOOTING.md
3. For allowlist issues, see [../06-besu/BESU_ALLOWLIST_QUICK_START.md](../06-besu/BESU_ALLOWLIST_QUICK_START.md)
4. **MetaMask "No XChain Swaps native asset found for chainId: eip155:138"** (on **Send** or Swap) — see [METAMASK_TROUBLESHOOTING_GUIDE.md](METAMASK_TROUBLESHOOTING_GUIDE.md#7-swap--bridge-in-wallet--and-send); workaround: send from a dApp, try another Send entry point, or use another wallet

## Related Documentation

- **[../03-deployment/OPERATIONAL_RUNBOOKS.md](../03-deployment/OPERATIONAL_RUNBOOKS.md)** - Operational procedures
- **[../06-besu/](../06-besu/)** - Besu configuration
- **[../08-monitoring/](../08-monitoring/)** - Monitoring guides