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)
```bash
# 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:
```bash
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:
```bash
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:**
```bash
# 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:**
```bash
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
```bash
# 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
```bash
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
```bash
cd app
python test_routes.py
```

Expected: List of routes including /login

### Step 4: Start Server
```bash
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'"
```bash
pip install Flask>=3.0.0
```

### Error: "ModuleNotFoundError: No module named 'werkzeug'"
```bash
pip install Werkzeug>=3.0.0
```

### Error: "Address already in use" / "Port 8080 is already in use"
```bash
# 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"
```bash
# 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
   ```python
   # 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:
   ```python
   SESSION_COOKIE_SECURE = True  # Only send cookies over HTTPS
   ```

4. **Set Debug=False** for production

---

## 📞 Still Having Issues?

1. Run the test script:
   ```bash
   python test_routes.py
   ```

2. Check Flask server output for errors:
   ```bash
   python app.py
   ```
   Look for red error messages

3. Test with curl:
   ```bash
   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.