docs: Add comprehensive troubleshooting guide for 404 errors and common issues

e-voting-system/TROUBLESHOOTING.md

@@ -0,0 +1,284 @@
+# Troubleshooting Guide
+
+## Issue: 404 on `/api/elections/active`
+
+### Diagnosis
+
+First, check what's actually in the database:
+
+```bash
+# Check all elections
+curl http://localhost:8000/api/elections/debug/all
+
+# Example response:
+{
+  "current_time": "2025-11-07T03:45:00.123456",
+  "elections": [
+    {
+      "id": 1,
+      "name": "Election Présidentielle 2025",
+      "is_active": true,
+      "start_date": "2025-11-06T02:45:00",
+      "end_date": "2025-11-14T02:45:00",
+      "should_be_active": true  ← Should be TRUE
+    },
+    {
+      "id": 2,
+      "name": "Présidentielle 2020",
+      "is_active": false,
+      "start_date": "2020-04-10T08:00:00",
+      "end_date": "2020-04-10T20:00:00",
+      "should_be_active": false
+    }
+  ]
+}
+```
+
+### Solution
+
+If no elections show `should_be_active: true`, follow these steps:
+
+#### Option 1: Fresh Database (Recommended)
+
+```bash
+# Stop containers
+docker-compose down
+
+# DELETE the database volume
+docker-compose down -v
+
+# Start fresh (will reinitialize)
+docker-compose up -d
+
+# Wait 30 seconds for database to initialize
+sleep 30
+
+# Verify elections were created
+curl http://localhost:8000/api/elections/debug/all
+
+# Now test active elections
+curl http://localhost:8000/api/elections/active
+```
+
+#### Option 2: Manually Fix via Adminer
+
+1. Go to http://localhost:8081
+2. Login:
+   - Server: `mariadb`
+   - User: `evoting_user`
+   - Password: `evoting_pass123`
+   - Database: `evoting_db`
+
+3. Run SQL in Adminer:
+   ```sql
+   -- Update election 1 to be active
+   UPDATE elections
+   SET
+       is_active = 1,
+       start_date = DATE_SUB(NOW(), INTERVAL 1 HOUR),
+       end_date = DATE_ADD(NOW(), INTERVAL 7 DAY)
+   WHERE id = 1;
+
+   -- Verify it worked
+   SELECT id, name, is_active, start_date, end_date FROM elections LIMIT 5;
+   ```
+
+4. Test API:
+   ```bash
+   curl http://localhost:8000/api/elections/active
+   ```
+
+#### Option 3: Direct Database Command
+
+```bash
+# Connect to MariaDB in Docker
+docker-compose exec mariadb mariadb -u evoting_user -pevoting_pass123 evoting_db
+
+# Run this SQL:
+UPDATE elections
+SET
+    is_active = 1,
+    start_date = DATE_SUB(NOW(), INTERVAL 1 HOUR),
+    end_date = DATE_ADD(NOW(), INTERVAL 7 DAY)
+WHERE id = 1;
+
+# Exit (Ctrl+D)
+
+# Test:
+curl http://localhost:8000/api/elections/active
+```
+
+### Root Cause
+
+The 404 occurs when:
+- No elections exist in database
+- All elections have `is_active = FALSE`
+- All elections have dates in the past (`end_date < NOW()`)
+- All elections have dates in the future (`start_date > NOW()`)
+
+The database initialization scripts should handle this, but if they don't:
+1. `docker/init.sql` creates 1 active election (ID 1)
+2. `docker/populate_past_elections.sql` creates 10 past elections (IDs 2-11)
+3. `docker/create_active_election.sql` ensures election 1 is always active
+
+If still getting 404 after these scripts run, use the manual fixes above.
+
+---
+
+## Issue: Empty Elections List on Frontend
+
+If `/api/elections/active` returns `[]` (empty list):
+
+### Check 1: Database has active elections
+```bash
+curl http://localhost:8000/api/elections/debug/all
+```
+
+### Check 2: Timezone issues
+- Docker database might be in different timezone
+- The endpoint now includes **1-hour buffer** on both sides to handle timezone skew
+- If still failing, the election dates are probably way off
+
+### Check 3: Frontend not fetching
+Open browser console (F12):
+```bash
+# Should show the fetch request
+GET http://localhost:3000/api/elections/active
+```
+
+If it's calling the **frontend** API instead of backend:
+- Frontend routes requests through its own API route
+- Check `frontend/lib/api.ts` for correct backend URL
+- Verify `NEXT_PUBLIC_API_URL` environment variable
+
+---
+
+## Issue: Vote Submission Fails
+
+### Error: "Impossible de charger les clés publiques"
+
+Election doesn't have ElGamal keys. Fix:
+```sql
+UPDATE elections
+SET elgamal_p = 23, elgamal_g = 5
+WHERE elgamal_p IS NULL OR elgamal_g IS NULL;
+```
+
+### Error: "Voter has already voted in this election"
+
+Voter already voted. To reset (for testing):
+```sql
+DELETE FROM votes WHERE voter_id = 1;  -- Replace 1 with voter ID
+UPDATE voters SET has_voted = FALSE WHERE id = 1;
+```
+
+### Error: "Candidate not found"
+
+Candidate doesn't exist for election. Check:
+```sql
+SELECT c.id, c.name, c.election_id
+FROM candidates c
+WHERE c.election_id = 1;  -- Replace 1 with election ID
+```
+
+---
+
+## Issue: Blockchain Not Showing Votes
+
+### Check: Votes recorded in database
+```sql
+SELECT COUNT(*) FROM votes;
+SELECT * FROM votes LIMIT 5;
+```
+
+### Check: Blockchain endpoint accessible
+```bash
+curl http://localhost:8000/api/votes/blockchain?election_id=1
+```
+
+### If no blocks:
+- Votes might be in database but blockchain not synced
+- Restart backend to reinitialize blockchain
+```bash
+docker-compose restart backend
+```
+
+---
+
+## Issue: Docker Container Won't Start
+
+### Check logs
+```bash
+docker-compose logs mariadb
+docker-compose logs backend
+docker-compose logs frontend
+```
+
+### Database won't start
+```bash
+# Check if port 3306 is already in use
+lsof -i :3306
+
+# Or check Docker volume issue
+docker volume ls
+docker volume rm evoting_data
+docker-compose up -d
+```
+
+### Backend won't connect to database
+Wait longer for MariaDB to start:
+```bash
+docker-compose up mariadb
+# Wait until you see: "ready for connections"
+# Then in another terminal:
+docker-compose up backend frontend
+```
+
+---
+
+## Debugging Checklist
+
+- [ ] Database initialized? `curl http://localhost:8000/api/elections/debug/all`
+- [ ] Active elections exist? Check response shows `"should_be_active": true`
+- [ ] Backend running? `docker-compose ps` shows `backend` healthy
+- [ ] Frontend built? `npm run build` succeeded with 0 errors
+- [ ] Elections endpoint returns data? `curl http://localhost:8000/api/elections/active`
+- [ ] Frontend can fetch? Check browser console for network requests
+- [ ] Votes can be submitted? Test via voting interface
+- [ ] Blockchain records votes? Check `/dashboard/blockchain`
+
+---
+
+## Quick Reset
+
+If everything is broken:
+
+```bash
+# Stop everything
+docker-compose down
+
+# Remove all data
+docker-compose down -v
+
+# Fresh start
+docker-compose up -d
+
+# Wait for initialization
+sleep 30
+
+# Check status
+curl http://localhost:8000/api/elections/debug/all
+curl http://localhost:8000/api/elections/active
+
+# Should be good now!
+```
+
+---
+
+## Contact Info
+
+For issues not covered here:
+- Check Docker logs: `docker-compose logs -f`
+- Check browser console: F12 in Chrome/Firefox
+- Check network requests: DevTools Network tab
+- Test API directly: `curl` or Postman