diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 00000000..9f9e7acf
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,82 @@
+# Raspberry Pi Troubleshooting Guide
+
+This guide provides solutions to common issues encountered while running IoT projects on Raspberry Pi devices.  
+It is designed for beginners following the IoT-For-Beginners curriculum, but is also useful for general Pi development.
+
+---
+
+## 1. Installation & Dependency Errors
+
+### ❗ `ModuleNotFoundError: No module named 'xyz'`
+This happens when required Python modules are not installed.
+
+**Fix**
+```bash
+pip3 install <module_name>
+
+ Permission denied when running scripts
+
+Often caused by accessing GPIO, I2C or system hardware without elevated privileges.
+Quick fix:
+sudo python3 script.py
+
+Recommended fix (no sudo needed every time):
+sudo usermod -aG gpio,i2c,spi $USER
+sudo reboot
+
+2. GPIO / I2C / SPI Not Working
+❗ RuntimeError: No access to GPIO
+
+Add user to GPIO group:
+sudo usermod -aG gpio $USER
+sudo reboot
+
+❗ I2C / SPI devices not detected
+
+Enable interfaces:
+sudo raspi-config
+→ Interface Options
+→ Enable I2C / Enable SPI
+
+Check if I2C device appears:
+i2cdetect -y 1
+
+3. Camera / Video Issues
+❗ Camera not detected or fails to start
+
+Enable camera interface:
+sudo raspi-config
+→ Interface Options → Camera → Enable
+sudo reboot
+
+Check if camera is visible:
+vcgencmd get_camera
+
+4. Wi-Fi / SSH / Connectivity Problems
+| Problem                          | Fix                                           |
+| -------------------------------- | --------------------------------------------- |
+| SSH connection refused           | `sudo raspi-config → Interface Options → SSH` |
+| Device not showing on network    | Check IP using: `hostname -I`                 |
+| Slow Wi-Fi / unstable connection | Prefer 2.4 GHz band, update OS                |
+| Unable to access Pi headless     | Add `ssh` file to boot partition              |
+
+
+5. Performance Issues
+Raspberry Pi running slow / laggy
+
+Close unused applications
+
+Reduce background services
+
+Use Lite OS if no desktop needed
+
+Ensure sufficient power supply (5V/3A or better)
+
+Check CPU load:
+top
+htop
+
+Storage issues:
+sudo apt autoremove
+sudo apt clean
+df -h