diff --git a/flash/troubleshooting.mdx b/flash/troubleshooting.mdx
index a2004f54..ea3bac4f 100644
--- a/flash/troubleshooting.mdx
+++ b/flash/troubleshooting.mdx
@@ -246,6 +246,35 @@ rm -rf .flash
 flash build
 ```
 
+### SSL certificate verification failed
+
+**Error:**
+```
+SSL certificate verification failed. This usually means Python cannot find your system's CA certificates.
+```
+
+**Cause:** Python cannot locate the system's trusted CA certificates, preventing secure connections during deployment. This commonly occurs on fresh Python installations, especially on macOS.
+
+**Solution:** Try one of these fixes:
+
+1. **Install certifi and set the certificate bundle path:**
+   ```bash
+   pip install certifi
+   export REQUESTS_CA_BUNDLE=$(python -c "import certifi; print(certifi.where())")
+   ```
+
+2. **macOS only:** Run the certificate installer that comes with Python. Find it in your Python installation folder (typically `/Applications/Python 3.x/`) and run `Install Certificates.command`.
+
+3. **Add to shell profile for persistence:**
+   ```bash
+   echo 'export REQUESTS_CA_BUNDLE=$(python -c "import certifi; print(certifi.where())")' >> ~/.bashrc
+   source ~/.bashrc
+   ```
+
+<Note>
+Transient SSL errors (like connection resets) are automatically retried during upload. The certificate verification error requires manual intervention because it indicates a system configuration issue.
+</Note>
+
 ### Resource provisioning failed
 
 **Error:**