diff --git a/docs/get-started/deploy-smart-contracts.mdx b/docs/get-started/deploy-smart-contracts.mdx
index 7554b28a..65c32abd 100644
--- a/docs/get-started/deploy-smart-contracts.mdx
+++ b/docs/get-started/deploy-smart-contracts.mdx
@@ -137,6 +137,49 @@ This will return the initial value of the Counter contract's `number` storage va
 
 **Congratulations! You've deployed your smart contracts to Base Sepolia!**
 
+## Troubleshooting
+
+### Common Issues and Solutions
+
+<Warning>
+If you encounter issues during deployment, check the solutions below before seeking additional help.
+</Warning>
+
+**Insufficient funds for gas**
+
+If you see an error about insufficient funds:
+- Verify your wallet has enough Base Sepolia ETH for gas fees
+- Get free test ETH from the [Base Sepolia faucets](/base-chain/tools/network-faucets)
+- Check your balance with: `cast balance <YOUR_ADDRESS> --rpc-url $BASE_SEPOLIA_RPC_URL`
+
+**Private key not found**
+
+If the deployment fails with a keystore error:
+- Confirm you imported the key correctly: `cast wallet list`
+- Re-import your private key: `cast wallet import deployer --interactive`
+- Ensure you're using the correct account name in the deployment command
+
+**RPC connection errors**
+
+If you cannot connect to the Base network:
+- Verify your `.env` file contains the correct RPC URL
+- Check that you loaded the environment variables: `echo $BASE_SEPOLIA_RPC_URL`
+- Try an alternative RPC endpoint if the default is unavailable
+
+**Contract compilation errors**
+
+If Forge cannot compile your contracts:
+- Run `forge build` to see detailed compilation errors
+- Ensure your Solidity version matches the pragma in your contract
+- Update Foundry to the latest version: `foundryup`
+
+**Deployment hangs or times out**
+
+If deployment appears stuck:
+- Check network status at [status.base.org](https://status.base.org)
+- Increase the gas limit if your contract is complex
+- Wait a few minutes and retry - the network may be congested
+
 ## Next Steps
 
 - Use [Onchainkit](https://onchainkit.com) to connect your frontend to your contracts! Onchainkit is a library of ready-to-use React components and Typescript utilities.