Troubleshooting

Common issues and their solutions.

Installation Issues

Python Module Not Found

Error:

ModuleNotFoundError: No module named 'flask'

Solution:

# Ensure virtual environment is activated
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows

# Reinstall dependencies
pip install -r requirements.txt

Port Already in Use

Error:

OSError: [Errno 48] Address already in use

Solution:

# Find and kill process using port 5000
# macOS/Linux
lsof -ti:5000 | xargs kill -9

# Windows
netstat -ano | findstr :5000
taskkill /PID <PID> /F

# Or use different port
PORT=5001 python app.py

npm Install Fails

Error:

npm ERR! code ELIFECYCLE

Solution:

# Clear cache
npm cache clean --force

# Delete and reinstall
rm -rf node_modules package-lock.json
npm install

Network Issues

Cannot Access from Other Devices

Symptoms: Server works on localhost but not from other devices

Solutions:

Check firewall:

# Windows: Allow Python through firewall
# Go to Windows Defender Firewall → Allow an app

# macOS: System Preferences → Security → Firewall

# Linux
sudo ufw allow 5000
sudo ufw allow 5173

Verify HOST setting:

# backend/.env
HOST=0.0.0.0  # NOT 127.0.0.1

Check network connectivity:

# From client device, ping server
ping 192.168.1.100

mDNS Not Working

Symptoms: Cannot connect via room code or .local address

Solutions:

Windows:

# Install Bonjour Print Services
# Download from Apple
# Or install iTunes (includes Bonjour)

macOS:

Bonjour is built-in and should work automatically.

Linux:

# Install Avahi
sudo apt install avahi-daemon avahi-utils

# Start service
sudo systemctl start avahi-daemon
sudo systemctl enable avahi-daemon

# Test
avahi-browse -a

CORS Errors

Error in browser console:

Access to fetch at 'http://192.168.1.100:5000/api/files'
from origin 'http://192.168.1.100:5173' has been blocked by CORS policy

Solution:

# backend/.env - Add your frontend URL
CORS_ORIGINS=http://localhost:5173,http://192.168.1.100:5173

# Restart backend server

Upload/Download Issues

Upload Fails

Error:

413 Request Entity Too Large

Solution:

# Increase max file size in backend/.env
MAX_CONTENT_LENGTH=524288000  # 500 MB

Error:

File type not allowed

Solution:

Check that file type is not restricted. By default, all file types are allowed.

Download Stuck at 0%

Symptoms: Download never progresses

Solutions:

Check browser console for JavaScript errors

Verify WebSocket connection:

// In browser console
console.log('Socket connected:', socket.connected)

Clear browser cache and reload
Try different browser

File Not Found After Upload

Symptoms: File uploads but doesn’t appear in list

Solutions:

Check upload folder permissions:

# Linux/macOS
chmod 755 backend/uploads

# Windows: Ensure user has write permissions

Verify file was uploaded:
```
ls backend/uploads/
```
Check backend logs for errors

WebSocket Issues

Connection Failed

Error in console:

WebSocket connection to 'ws://localhost:5000/socket.io/' failed

Solutions:

Check backend is running

Verify Socket.IO versions match:

# backend/requirements.txt
flask-socketio==5.3.0

# frontend/package.json
"socket.io-client": "^4.5.0"

Check proxy configuration in vite.config.js

Real-Time Updates Not Working

Symptoms: Files uploaded but clients don’t see them immediately

Solutions:

Refresh page (force reload: Ctrl+Shift+R)

Check WebSocket connection:

// Browser console
socket.on('connect', () => console.log('Connected!'))
socket.on('disconnect', () => console.log('Disconnected!'))

Restart both backend and frontend

Authentication Issues

Incorrect PIN Error

Error:

Invalid PIN

Solutions:

Check ACCESS_PIN in backend/.env

Ensure no extra spaces:

ACCESS_PIN=1234  # Correct
ACCESS_PIN= 1234  # Wrong (extra space)

Restart backend after changing PIN

Session Expired

Error:

Session expired, please log in again

Solutions:

Clear browser cookies
Check SECRET_KEY hasn’t changed
Re-enter PIN to create new session

Performance Issues

Slow Upload/Download

Symptoms: Transfer speeds slower than expected

Solutions:

Use wired connection instead of WiFi
Close other network applications

Check network speed:

# Test with iperf3
# Server
iperf3 -s

# Client
iperf3 -c 192.168.1.100

Reduce MAX_CONTENT_LENGTH if system has limited memory

High Memory Usage

Symptoms: Backend using excessive RAM

Solutions:

Enable FILE_TTL_SECONDS for auto-deletion:

FILE_TTL_SECONDS=3600  # Delete after 1 hour

Manually delete old files
Reduce MAX_CONTENT_LENGTH
Restart backend periodically

Browser Issues

Files Not Displaying

Symptoms: Blank file list

Solutions:

Check browser console (F12) for errors
Try incognito/private mode
Clear cache and cookies
Update browser to latest version

Drag & Drop Not Working

Symptoms: Cannot drag files to upload area

Solutions:

Click to browse instead
Check browser supports File API
Try different browser (Chrome, Firefox, Edge)
Disable browser extensions temporarily

Advanced Troubleshooting

Enable Debug Logging

Backend:

# app.py - Add at top
import logging
logging.basicConfig(level=logging.DEBUG)

Frontend:

// Enable Socket.IO debug
localStorage.debug = '*';

Check Server Logs

# Backend logs show in terminal where you ran:
python app.py

# Look for errors, warnings, or stack traces

Test API Endpoints

# Test server is responding
curl http://localhost:5000/api/info

# Test file list
curl http://localhost:5000/api/files

Network Diagnostics

# Check if port is open
telnet 192.168.1.100 5000

# Check connectivity
ping 192.168.1.100

# Trace route
traceroute 192.168.1.100  # macOS/Linux
tracert 192.168.1.100     # Windows

Reset Everything

If all else fails:

# 1. Stop all services
# Press Ctrl+C in backend and frontend terminals

# 2. Clear uploads
rm -rf backend/uploads/*

# 3. Delete virtual environment
rm -rf backend/venv

# 4. Recreate environment
cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 5. Clear frontend cache
cd ../frontend
rm -rf node_modules package-lock.json
npm install

# 6. Restart everything
# Terminal 1
cd backend
python app.py

# Terminal 2
cd frontend
npm run dev

Getting Help

If you’re still experiencing issues:

Search existing issues: GitHub Issues
Create new issue: Include: - Operating system and version - Python version (python --version) - Node.js version (node --version) - Error messages (full text) - Steps to reproduce
Check FAQ: Frequently Asked Questions for common questions
Join discussions: GitHub Discussions

Error Reference

Error Code	Meaning	Solution
400	Bad Request	Check request parameters
401	Unauthorized	Enter correct PIN
403	Forbidden	Check file permissions
404	Not Found	Verify file exists
413	Payload Too Large	Increase MAX_CONTENT_LENGTH
429	Too Many Requests	Wait before retrying
500	Server Error	Check backend logs