werkzeuge/teamleader_test/docs/guides/troubleshooting.md

Troubleshooting Guide

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

---

Quick Diagnostics

Health Check

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

// 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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

# 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

# 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

# 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:

# 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
4. Review code review archive: archive/review-2025-12-04/
5. Verify project status: docs/project-status.md

---

Last Updated: December 4, 2025