Troubleshooting Guide - PCB Stackup Generator¶

Recent Fixes (2025-10-04)¶

Issue: Network Errors and CORS Failures¶

Symptoms: - ❌ Component API Error: Network Error - POST https://localhost:8000/api/components/search net::ERR_SSL_PROTOCOL_ERROR - Access to fetch at 'https://pcbgenerator.com/api/api/agent/select-pa' from origin 'http://localhost:5180' has been blocked by CORS policy - 307 Temporary Redirect on API endpoints

Root Causes: 1. Frontend running in production mode during development 2. HTTPS redirect middleware active in development 3. Missing VITE_* variables in the root .env (Vite reads env from the repo-root .env via envDir — frontend/.env is ignored at runtime and deleted by the start script) 4. Double /api path in production URL configuration 5. Restrictive CORS settings blocking localhost requests

Fixes Applied:

1. Backend (`backend/main.py`)¶

✅ Disabled HTTPS redirect in development mode
✅ Changed CORS to allow all origins (*) in development
✅ Updated security headers to only apply in production

2. Frontend Configuration¶

✅ Fixed frontend/src/config/api.ts to properly detect development mode
✅ Fixed frontend/src/config.ts to respect environment variables
✅ Set correct API URLs in the root .env (Vite reads env from the repo root)
✅ Fixed double /api path issue in production URLs

3. Environment Setup¶

Set in the root .env (do NOT use frontend/.env — Vite ignores it and start-all-servers-windowed.ps1 deletes it):

VITE_FASTAPI_URL=http://localhost:8000
VITE_API_URL=http://localhost:8000
VITE_FORCE_HTTPS=false

How to Fix Network Errors¶

Step 1: Verify Environment Files¶

Check the root .env contains:

Get-Content .env | Select-String "VITE_"

Should include:

VITE_FASTAPI_URL=http://localhost:8000
VITE_API_URL=http://localhost:8000
VITE_FORCE_HTTPS=false

If missing, add these lines to the root .env. Do not create frontend/.env — Vite reads env only from the repo-root .env (envDir in frontend/vite.config.ts), and start-all-servers-windowed.ps1 deletes frontend/.env on every run.

Step 2: Restart All Servers¶

Important: You MUST restart the frontend after changing .env files!

.\start-all-servers-windowed.ps1

Step 3: Verify Backend is Running¶

Check the FastAPI backend window shows:

INFO:     Application startup complete.
🔧 Development mode: HTTPS redirect disabled
🔧 Development mode: All CORS origins allowed

Step 4: Check Browser Console¶

Open browser console (F12) and look for:

🔧 API Configuration:
  isProduction: false
  isDevelopment: true
  protocol: "http:"
  fastApiURL: "http://localhost:8000"

If you see https:// URLs or isProduction: true, the environment file isn't being loaded.

Common Issues¶

Issue: Still Getting HTTPS Errors¶

Symptom: ERR_SSL_PROTOCOL_ERROR or https://localhost:8000

Solution: 1. Stop all servers 2. Clear browser cache (Ctrl+Shift+Delete) 3. Delete frontend/node_modules/.vite cache:

Remove-Item -Recurse -Force frontend\node_modules\.vite

4. Restart servers 5. Hard reload browser (Ctrl+Shift+R)

Issue: CORS Errors¶

Symptom: No 'Access-Control-Allow-Origin' header is present

Solution: 1. Verify backend shows: 🔧 Development mode: All CORS origins allowed 2. If not, check config\.env doesn't have ENVIRONMENT=production 3. Restart backend

Issue: 307 Redirects¶

Symptom: POST /api/components/search HTTP/1.1" 307 Temporary Redirect

Solution: - This was fixed in backend/main.py - Ensure you're running the updated backend - Backend should show: 🔧 Development mode: HTTPS redirect disabled

Issue: Double `/api` Path¶

Symptom: URLs like https://pcbgenerator.com/api/api/agent/select-pa

Solution: - Fixed in frontend/src/config/api.ts - Production URL changed from https://pcbgenerator.com to https://pcbgenerator.com/api - Restart frontend

Verification Checklist¶

After restart, verify:

FastAPI backend running on http://localhost:8000
React frontend running on http://localhost:5180
Backend logs show "Development mode" messages
Browser console shows isProduction: false
No HTTPS URLs in browser console API configuration
Component search works without network errors
No CORS errors in browser console

Development vs Production¶

Development Mode (Current)¶

Protocol: HTTP
CORS: Allow all origins (*)
HTTPS Redirect: Disabled
Security Headers: Disabled
FastAPI: http://localhost:8000
Frontend (Vite): http://localhost:5180

Production Mode (Deployment)¶

Protocol: HTTPS
CORS: Specific origins only
HTTPS Redirect: Enabled
Security Headers: Enabled (HSTS, CSP, etc.)
FastAPI: https://pcbgenerator.com/api

Debug Commands¶

Check Backend Configuration¶

# View backend environment variables
Get-Content config\.env

# Test backend health
curl http://localhost:8000/health

# Test component search endpoint
curl -X OPTIONS http://localhost:8000/api/components/search

Check Frontend Configuration¶

# View frontend (Vite) environment variables — read from the ROOT .env
Get-Content .env | Select-String "VITE_"

# Check if frontend is using them
# Open browser console and check API_CONFIG

Clear Everything and Start Fresh¶

# Stop all servers
Get-Process -Name "node","python","uvicorn" -ErrorAction SilentlyContinue | Stop-Process -Force

# Clear frontend cache
Remove-Item -Recurse -Force frontend\node_modules\.vite

# Verify the root .env has the VITE_ URLs (frontend/.env is ignored by Vite
# and deleted by the start script)
Get-Content .env | Select-String "VITE_FASTAPI_URL|VITE_API_URL|VITE_FORCE_HTTPS"

# Restart all
.\start-all-servers-windowed.ps1

Still Having Issues?¶

Check the backend FastAPI window for detailed error logs
Check the browser console for detailed frontend errors
Verify ports 8000 and 5180 aren't blocked by firewall
Try accessing http://localhost:8000/docs to test FastAPI directly
Check if antivirus is blocking local network connections

Contact¶

If issues persist, provide: 1. Backend console output (from FastAPI window) 2. Browser console output (full error stack) 3. VITE_* lines from the root .env (redact secrets) 4. Output of: Get-Content config\.env