CGW-Quote-Builder/information/TROUBLESHOOTING_404.md

Troubleshooting Guide - 404 Errors & Installation Issues

🔴 Issue 1: pip install requirements.txt fails

Error Message:

error: subprocess-exited-with-error
× Getting requirements to build wheel did not run successfully.

Solution:

This error usually happens with Pillow on Windows systems that don't have build tools installed.

Option 1: Install Pre-built Pillow (Recommended)

# Upgrade pip first
python -m pip install --upgrade pip

# Install Pillow from pre-built wheels
pip install --upgrade Pillow

# Then install other requirements
pip install Flask>=3.0.0
pip install Werkzeug>=3.0.0

Option 2: Install from updated requirements.txt

The requirements.txt has been updated to use version ranges instead of exact versions:

pip install -r requirements.txt

Option 3: Skip Pillow (if you don't need image generation)

If you don't need the dynamic image generation feature, you can install without Pillow:

pip install Flask>=3.0.0
pip install Werkzeug>=3.0.0

The app will still work - it will just disable the image generation features.

---

🔴 Issue 2: Login Page Returns 404 Error

Common Causes & Solutions:

Cause 1: Flask Server Not Running

Check if the server is running:

# Navigate to app folder
cd "C:\Users\Work\Desktop\CGW Product Finder\app"

# Run the Flask app
python app.py

You should see:

✓ Image generation available
 * Running on http://127.0.0.1:8080

Then access: http://localhost:8080/login

---

Cause 2: Wrong URL or Port

Common mistakes:

❌ http://localhost/login - Missing port number ✅ http://localhost:8080/login - Correct

❌ http://localhost:5000/login - Wrong port ✅ http://localhost:8080/login - Correct (app uses port 8080)

❌ /login in browser address bar ✅ http://localhost:8080/login - Need full URL

---

Cause 3: Flask App Import Error

Test if routes are registered:

cd app
python test_routes.py

This will show:

• If Flask imports successfully
• All registered routes including /login
• What went wrong if there's an error

Expected output:

✓ Flask app imported successfully

📝 Login & Authentication Routes:
  /login                    [GET]            -> login_page
  /api/login               [POST]           -> login
  /api/logout              [POST]           -> logout

---

Cause 4: Web Server Configuration (Apache/Passenger/IIS)

If you're running through a web server instead of python app.py:

Check your server configuration:

For Apache + Passenger:

• Verify passenger_wsgi.py is being used
• Check if Python path is correct in config
• Ensure the app folder is set as DocumentRoot

For IIS:

• Verify web.config is correct
• Check if Python handler is configured
• Ensure proper app folder path

Test directly first: Always test with python app.py first to verify the app works before troubleshooting web server issues.

---

📋 Step-by-Step Troubleshooting

Step 1: Verify Installation

# Check Python version (need 3.7+)
python --version

# Check if Flask is installed
python -c "import flask; print(flask.__version__)"

# Check if Werkzeug is installed
python -c "import werkzeug; print(werkzeug.__version__)"

Step 2: Fresh Install

cd "C:\Users\Work\Desktop\CGW Product Finder\app"

# Upgrade pip
python -m pip install --upgrade pip

# Install requirements
pip install -r requirements.txt

# Or manual install
pip install Flask>=3.0.0 Werkzeug>=3.0.0 Pillow>=10.0.0

Step 3: Test Routes

cd app
python test_routes.py

Expected: List of routes including /login

Step 4: Start Server

python app.py

Expected output:

✓ Image generation available
 * Running on http://127.0.0.1:8080
 * Running on http://192.168.x.x:8080

Step 5: Access in Browser

Open browser: http://localhost:8080/login

Expected: Login page with username/password fields

---

🐛 Common Errors & Fixes

Error: "ModuleNotFoundError: No module named 'flask'"

pip install Flask>=3.0.0

Error: "ModuleNotFoundError: No module named 'werkzeug'"

pip install Werkzeug>=3.0.0

Error: "Address already in use" / "Port 8080 is already in use"

# Find what's using port 8080
netstat -ano | findstr :8080

# Kill the process (replace PID with actual process ID)
taskkill /PID <PID> /F

# Or edit app.py to use different port (line 911):
app.run(debug=True, host='0.0.0.0', port=8090)

Error: "Template Not Found: login.html"

# Verify template exists
dir templates\login.html

# If missing, the file needs to be uploaded to the server

Error: "Working outside of application context"

This means Flask app isn't initialized properly. Run python test_routes.py to diagnose.

---

✅ Verification Checklist

After fixing issues, verify:

• Flask server starts without errors: python app.py
• http://localhost:8080/ redirects to http://localhost:8080/login ✓
• http://localhost:8080/login shows login page ✓
• Can login with username: Master password: Master ✓
• After login, see location selection page ✓
• Can access user management (Master user only) ✓
• Logout works and returns to login page ✓

---

🚀 Production Deployment

For production servers (not localhost):

1. Use proper WSGI server (not python app.py)

   • Passenger (Apache/Nginx)
   • uWSGI
   • Gunicorn (Linux)

2. Set secure SECRET_KEY in config.py

   # Don't use secrets.token_hex() in production
   SECRET_KEY = os.environ.get('SECRET_KEY') or 'your-secure-random-key-here'
   

3. Enable HTTPS and update config:

   SESSION_COOKIE_SECURE = True  # Only send cookies over HTTPS
   

4. Set Debug=False for production

---

📞 Still Having Issues?

1. Run the test script:

   python test_routes.py
   

2. Check Flask server output for errors:

   python app.py
   

   Look for red error messages

3. Test with curl:

   curl http://localhost:8080/login
   

   Should return HTML, not 404

4. Check browser console for JavaScript errors (F12)

5. Verify file permissions (server can read templates/)

---

📁 Files Needed for Login System

Ensure these files exist and are uploaded:

• ✅ app/app.py
• ✅ app/templates/login.html
• ✅ app/templates/user_manager.html
• ✅ app/templates/access_denied.html
• ✅ app/templates/select_location.html
• ✅ app/templates/index2.html
• ✅ app/css/styles.css
• ✅ app/data/users.json

Missing any of these will cause 404 or errors.