Connection Issues
ICE Server Connection Failed
The most common issue is when the Flask web server cannot connect to the ICE server.
The web server depends on the ICE server running on port 10000. Always start the ICE server first.
Verify ICE server is running
Check if server.py is running: macOS/Linux
Windows PowerShell
Expected output:COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
python3 12345 user 4u IPv4 0x1234 0t0 TCP *:10000 (LISTEN)
netstat -ano | findstr :10000
TCP 0.0.0.0:10000 0.0.0.0:0 LISTENING 12345
Start the ICE server
In a dedicated terminal:cd backend
python3 server.py
Servidor ICE iniciado en puerto 10000
Presiona Ctrl+C para detener
Check for port conflicts
If port 10000 is already in use by another process, you’ll need to either:
- Stop the conflicting process
- Modify the port in both
server.py and web_server.py
Web Server Port Conflict (5000)
Flask’s default port 5000 may be occupied by other services.
Check what's using port 5000
macOS/Linux
Windows PowerShell
netstat -ano | findstr :5000
You can run Flask on a different port using environment variables: macOS/Linux
Windows PowerShell
Windows CMD
HOST=0.0.0.0 PORT=8080 DEBUG=true python backend/web_server.py
$env:HOST="0.0.0.0"
$env:PORT="8080"
$env:DEBUG="true"
python backend/web_server.py
set HOST=0.0.0.0
set PORT=8080
set DEBUG=true
python backend\web_server.py
http://localhost:8080 Dependency Issues
zeroc-ice Installation Failure
The zeroc-ice package can be tricky to install depending on your Python version and system.
Recommended Python versions: 3.10 or 3.11Python 3.12+ may have compatibility issues with zeroc-ice 3.7.x.
Upgrade pip
Always ensure pip is up-to-date before installing:python -m pip install --upgrade pip
Use Python 3.10 or 3.11
Check your Python version:If you’re using an incompatible version, install Python 3.10 or 3.11 and create a new virtual environment with it:# Install Python 3.11 via Homebrew
brew install [email protected]
# Create venv with specific version
python3.11 -m venv .venv
source .venv/bin/activate
Download Python 3.11 from python.org# Create venv with specific version
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
Reinstall in clean environment
If issues persist, create a fresh virtual environment:# Remove old environment
rm -rf .venv
# Create new one
python3 -m venv .venv
source .venv/bin/activate # or .venv\Scripts\Activate.ps1 on Windows
# Install dependencies
python -m pip install --upgrade pip
pip install -r requirements.txt
Flask Installation Issues
The project requires Flask 3.0+:
pip install "Flask>=3.0,<4.0"
Frontend Issues
Changes Not Appearing in Browser
Browser caching can prevent you from seeing frontend updates.
Force the browser to fetch fresh assets:Press Ctrl+F5 or Ctrl+Shift+R
Press Cmd+Shift+R
Press Ctrl+F5 or Ctrl+Shift+R
If hard reload doesn’t work:
- Open browser DevTools (F12)
- Right-click the refresh button
- Select “Empty Cache and Hard Reload”
Make sure Flask is running in debug mode:# In web_server.py, ensure:
app.run(host='localhost', port=5000, debug=True)
API Endpoint Not Found (404)
If API calls return 404 errors:
Verify Flask server is running
Check the terminal running web_server.py for error messages.
Check the endpoint URL
The available endpoints are:
POST /api/convertGET /api/unidades/<categoria>GET /api/status
Ensure you’re using the correct HTTP method and path. Test with curl
Verify endpoints work independently:# Test status
curl http://localhost:5000/api/status
# Test conversion
curl -X POST http://localhost:5000/api/convert \
-H "Content-Type: application/json" \
-d '{"categoria":"temperatura","valor":32,"desde":"fahrenheit","hasta":"celsius"}'
Virtual Environment Issues
PowerShell Script Execution Blocked (Windows)
Windows PowerShell may block the activation script by default.
If you see: cannot be loaded because running scripts is disabled on this system
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
This setting only affects the current PowerShell window and resets when you close it.
Wrong Python Version in venv
If your virtual environment uses the wrong Python version:
Create venv with specific version
python3.11 -m venv .venv
source .venv/bin/activate
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
Reinstall dependencies
python -m pip install --upgrade pip
pip install -r requirements.txt
ngrok Issues
ngrok Command Not Found
If ngrok is not installed:
macOS
Windows (winget)
Windows (Chocolatey)
winget install ngrok.ngrok
ngrok Authentication Required
First time using ngrok? You need to add your auth token:
ngrok config add-authtoken YOUR_TOKEN
Process Management
Orphaned Server Processes
If servers keep running after closing terminals:
macOS/Linux
Windows PowerShell
# Find processes
lsof -i :10000
lsof -i :5000
# Kill by PID
kill -9 <PID>
# Or kill all Python processes (use with caution)
pkill -f server.py
pkill -f web_server.py
# Find processes
netstat -ano | findstr :10000
netstat -ano | findstr :5000
# Kill by PID
taskkill /PID <PID> /F
# Or kill by name
taskkill /IM python.exe /F
The automated run scripts (run.sh and run.ps1) include cleanup handlers that stop servers when you press Ctrl+C.
Still Having Issues?
If none of these solutions work:
Verify all dependencies
Should show Flask and zeroc-ice Test ICE client directly
This bypasses the web server and tests ICE directly Check system requirements
- Ensure ports 10000 and 5000 are not blocked by firewall
- Verify you have network access (even localhost requires it)
- Check for antivirus software blocking connections