werkzeuge/teamleader_test/docs/guides/troubleshooting.md

# Troubleshooting Guide

Common errors, solutions, and debugging procedures for the Network Scanner Tool.

---

## Quick Diagnostics

### Health Check
```bash
# Check if services are running
docker compose ps

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

# Check logs
docker compose logs backend --tail=50
docker compose logs frontend --tail=50
```

---

## Common Errors & Solutions

### Backend Errors

#### ❌ `500 Internal Server Error` on API calls

**Symptoms**: API returns 500 error, backend logs show exceptions

**Common Causes**:
1. **Schema mismatch** between backend (Pydantic) and frontend (TypeScript)
2. **Database constraint violation** (NOT NULL, UNIQUE, etc.)
3. **SQLAlchemy DetachedInstanceError** in background tasks

**Solutions**:

**Schema Mismatch**:
```bash
# Check if frontend/src/types/api.ts matches app/schemas.py
# Example: Backend returns "network_range" but frontend expects "target"

# Fix: Update TypeScript interface
# frontend/src/types/api.ts
export interface Scan {
  network_range: string;  // ← Must match backend exactly
  // not: target: string;
}
```

**Database Constraint**:
```python
# Error: NOT NULL constraint failed: services.host_id
# Cause: Services added before host committed

# Fix: Commit and refresh host BEFORE adding services
host = self._get_or_create_host(ip)
self.db.commit()      # ← CRITICAL: Ensure host.id is set
self.db.refresh(host)

# NOW safe to add services
service = Service(host_id=host.id, port=80)
self.db.add(service)
```

**DetachedInstanceError**:
```python
# Error: Instance is not bound to a Session
# Cause: Using request session in background task

# Fix: Create new session in background task
def scan_wrapper(scan_id: int):
    db = SessionLocal()  # ← New session
    try:
        scan_service.execute_scan(scan_id, db)
    finally:
        db.close()

background_tasks.add_task(scan_wrapper, scan_id)
```

#### ❌ `TopologyNode object has no field "position"`

**Symptoms**: `/api/topology` returns 500, logs show Pydantic validation error

**Cause**: Code trying to set field that doesn't exist in schema

**Solution**:
```python
# Check app/schemas.py - ensure TopologyNode has required fields
class TopologyNode(BaseModel):
    id: str
    ip: str
    hostname: Optional[str]
    type: str
    status: str
    service_count: int
    connections: int
    # NOTE: No "position" field in simplified schema

# Remove any code that sets node.position
# Don't use _calculate_layout() if it sets positions
```

#### ❌ `Database is locked`

**Symptoms**: SQLite database errors, operations timeout

**Cause**: SQLite only allows one writer at a time

**Solutions**:
1. Close other database connections
2. Wait for running scans to complete
3. Restart backend: `docker compose restart backend`
4. For production with high concurrency, use PostgreSQL

---

### Frontend Errors

#### ❌ Blank page / White screen

**Symptoms**: Frontend loads but shows nothing

**Debugging**:
```bash
# 1. Open browser console (F12)
# 2. Check for JavaScript errors

# Common errors:
# - "Cannot read property 'X' of undefined" → API returned unexpected structure
# - "Network Error" → Backend not running or wrong URL
# - "TypeError: X is not a function" → Missing dependency or wrong import
```

**Solutions**:
```bash
# Check VITE_API_URL environment variable
# frontend/.env
VITE_API_URL=http://localhost:8000

# Verify backend is running
curl http://localhost:8000/health

# Rebuild frontend
docker compose up -d --build frontend
```

#### ❌ TypeScript build errors

**Symptoms**: `docker compose up --build` fails with TS errors

**Common Errors**:
```typescript
// Error: Type X is not assignable to type Y
// Fix: Check frontend/src/types/api.ts matches backend response

// Error: Property 'X' does not exist on type 'Y'
// Fix: Add missing property to interface or use optional chaining

// Error: 'X' is declared but its value is never read
// Fix: Remove unused variable or use underscore: _unused
```

#### ❌ Network map crashes or doesn't display

**Symptoms**: Network page loads but map is blank or crashes

**Debugging**:
```bash
# Check topology API response structure
curl -s http://localhost:8000/api/topology | jq .

# Should return:
{
  "nodes": [{"id": "1", "ip": "...", ...}],
  "edges": [{"source": "1", "target": "2", ...}],
  "statistics": {...}
}
```

**Solutions**:
- Verify `topology.nodes` is an array
- Check node objects have required fields: `id`, `ip`, `type`, `status`
- Ensure edge objects have: `source`, `target`, `type`
- Run a scan first to populate data

---

### Docker & Deployment Errors

#### ❌ `Cannot start service backend: Ports are not available`

**Symptoms**: Docker Compose fails to start, port 8000 or 80 in use

**Solution**:
```bash
# Find process using port
lsof -ti:8000
lsof -ti:80

# Kill process or stop conflicting container
docker stop $(docker ps -q)

# Or change ports in docker-compose.yml
services:
  backend:
    ports:
      - "8001:8000"  # Use different host port
```

#### ❌ `no such file or directory: ./data/network_scanner.db`

**Symptoms**: Backend can't access database

**Solution**:
```bash
# Create data directory
mkdir -p /home/rwiegand/Nextcloud/entwicklung/Werkzeuge/teamleader_test/data

# Check volume mounting in docker-compose.yml
volumes:
  - ./data:/app/data

# Restart containers
docker compose down && docker compose up -d
```

#### ❌ Container keeps restarting

**Symptoms**: `docker compose ps` shows container constantly restarting

**Debugging**:
```bash
# Check container logs
docker compose logs backend --tail=100

# Common issues:
# - Missing environment variables
# - Failed database initialization
# - Port conflicts
# - Import errors (missing dependencies)
```

---

### Scanning Errors

#### ❌ Scan starts but nothing is discovered

**Symptoms**: Scan completes but finds 0 hosts

**Causes**:
1. Network range is wrong or unreachable
2. Firewall blocking outgoing connections
3. Hosts are actually offline

**Solutions**:
```bash
# Test network connectivity manually
ping 192.168.1.1

# Verify network range syntax
# Correct: "192.168.1.0/24"
# Wrong: "192.168.1.0-255", "192.168.1.*"

# Check if you're on the correct network
ip addr show

# Try scanning your own machine
curl -X POST http://localhost:8000/api/scans/start \
  -H "Content-Type: application/json" \
  -d '{"network_range":"127.0.0.1/32","scan_type":"quick"}'
```

#### ❌ Scan never completes / hangs

**Symptoms**: Scan status stays "running" indefinitely

**Debugging**:
```bash
# Check backend logs for errors
docker compose logs backend --tail=100 | grep -i error

# Check if scan is actually running
curl http://localhost:8000/api/scans/1/status

# Look for exceptions in logs
docker compose logs backend | grep -i "exception\|traceback"
```

**Solutions**:
```bash
# Cancel stuck scan
curl -X DELETE http://localhost:8000/api/scans/1/cancel

# Restart backend
docker compose restart backend

# If persists, check for:
# - Deadlocks (check cancel_requested flag)
# - Infinite loops in scan logic
# - Background task not properly yielding
```

#### ❌ Progress bar doesn't update

**Symptoms**: Scan starts but progress stays at 0%

**Cause**: WebSocket not connected or not receiving updates

**Solutions**:
```bash
# Check WebSocket connection in browser console (F12)
# Should see: "WebSocket connected. Total connections: 1"

# Verify WebSocket endpoint
curl --include \
     --no-buffer \
     --header "Connection: Upgrade" \
     --header "Upgrade: websocket" \
     --header "Sec-WebSocket-Version: 13" \
     --header "Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ==" \
     http://localhost:8000/api/ws

# Check backend WebSocket handler
# app/api/endpoints/websocket.py should broadcast progress
```

---

### Database Errors

#### ❌ `PendingRollbackError`

**Symptoms**: Operations fail with "can't reconnect until invalid transaction is rolled back"

**Cause**: Exception occurred but transaction wasn't rolled back

**Solution**:
```python
# Wrap operations in try/except with rollback
try:
    # Database operations
    self.db.commit()
except Exception as e:
    self.db.rollback()  # ← CRITICAL
    logger.error(f"Error: {e}")
    raise
```

#### ❌ Column doesn't exist after schema change

**Symptoms**: `no such column: connections.extra_data`

**Cause**: Database schema doesn't match models

**Solution**:
```bash
# For development: Delete and recreate database
rm data/network_scanner.db
docker compose restart backend

# For production: Create migration
# (Requires alembic setup - TODO)
```

---

## Debugging Procedures

### Backend Debugging

```bash
# 1. Enable debug logging
# Edit .env
DEBUG=True
LOG_LEVEL=DEBUG

# 2. Restart backend
docker compose restart backend

# 3. Watch logs in real-time
docker compose logs -f backend

# 4. Test specific endpoint
curl -v http://localhost:8000/api/hosts

# 5. Check database state
docker compose exec backend python -c "
from app.database import SessionLocal
from app.models import Host
db = SessionLocal()
print('Hosts:', db.query(Host).count())
"
```

### Frontend Debugging

```bash
# 1. Open browser DevTools (F12)
# 2. Check Console tab for errors
# 3. Check Network tab for failed API calls
# 4. Use React DevTools extension

# Test API directly
curl http://localhost:8000/api/topology

# Check if response matches TypeScript types
# Compare with frontend/src/types/api.ts
```

### Network Issues

```bash
# Test backend API from host
curl http://localhost:8000/health

# Test from inside frontend container
docker compose exec frontend wget -O- http://backend:8000/health

# Check DNS resolution
docker compose exec frontend nslookup backend

# Verify network connectivity
docker network inspect teamleader_test_scanner-network
```

---

## Performance Issues

### Slow Scans

**Symptoms**: Scans take much longer than expected

**Solutions**:
1. **Reduce concurrency**: Edit `app/config.py`, set `MAX_CONCURRENT_SCANS = 25`
2. **Increase timeout**: Set `DEFAULT_SCAN_TIMEOUT = 5`
3. **Use quick scan**: Only scan common ports
4. **Reduce network range**: Scan /28 instead of /24

### High Memory Usage

**Symptoms**: Docker containers using excessive memory

**Solutions**:
```bash
# Limit container memory
# docker-compose.yml
services:
  backend:
    deploy:
      resources:
        limits:
          memory: 512M

# Reduce concurrent scans
# app/config.py
MAX_CONCURRENT_SCANS = 25
```

---

## Getting Help

If issues persist:

1. **Check logs**: `docker compose logs backend --tail=100`
2. **Review this guide**: Common solutions above
3. **Check copilot instructions**: [.github/copilot-instructions.md](../.github/copilot-instructions.md)
4. **Review code review archive**: [archive/review-2025-12-04/](../archive/review-2025-12-04/)
5. **Verify project status**: [docs/project-status.md](project-status.md)

---

**Last Updated**: December 4, 2025