From 5177221b9c1ea52b93557a9178355d214d3a07ad Mon Sep 17 00:00:00 2001 From: Alexis Bruneteau Date: Fri, 7 Nov 2025 02:55:59 +0100 Subject: [PATCH] docs: Add comprehensive troubleshooting guide for 404 errors and common issues --- e-voting-system/TROUBLESHOOTING.md | 284 +++++++++++++++++++++++++++++ 1 file changed, 284 insertions(+) create mode 100644 e-voting-system/TROUBLESHOOTING.md diff --git a/e-voting-system/TROUBLESHOOTING.md b/e-voting-system/TROUBLESHOOTING.md new file mode 100644 index 0000000..1cc414e --- /dev/null +++ b/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