Troubleshooting#

This section provides solutions to common issues and error messages.

Common Issues#

Cannot Access the UI#

Symptom: Browser shows “Unable to connect” or “Connection refused”

Possible Causes:

  • Backend server is not running

  • Incorrect URL or port

  • Network connectivity issues

  • Firewall blocking access

Solutions:

  1. Verify Server is Running

    # Check Docker container status
docker ps | grep auto-calib

# Or check docker compose services
docker compose ps

  2. Verify URL and Port

    • Check the URL in your browser address bar

    • Verify the port number matches server configuration

    • Try accessing from the server machine: http://localhost:<port>

  3. Check Network Connectivity

    # Ping the server
ping <server-ip>

# Check if port is accessible
telnet <server-ip> <port>

  4. Check Firewall Settings

    • Ensure firewall allows traffic on the UI port

    • Check both server and client firewalls

    • Temporarily disable firewall to test (not recommended for production)

Port Already in Use#

Symptom: Docker container fails to start with “port is already allocated” error

Cause: Another application or container is already using the configured port (default: 5000 for UI, 8000 for backend)

Solution:

  1. Check what’s using the port:

    # Check which process is using a specific port
sudo lsof -i :5000
sudo lsof -i :8000

# Or using netstat
sudo netstat -tulpn | grep :5000

  2. Use a different port: Update your .env file with different ports:

    # Edit .env file
VSS_AUTO_CALIBRATION_PORT=8001
VSS_AUTO_CALIBRATION_UI_PORT=5001

    Then restart the services:

    docker compose --profile "bp_wh_2d" down
docker compose --profile "bp_wh_2d" up

  3. Stop the conflicting service (if safe to do so):

    # Kill the process using the port (replace PID with actual process ID)
sudo kill <PID>

# Or stop conflicting Docker containers
docker compose down

API_URL_NOT_PROVIDED Error#

Symptom: UI loads but shows “API_URL_NOT_PROVIDED” error

Cause: Docker Compose started without proper HOST_IP environment variable

Solution:

  1. Stop the services:

    docker compose --profile "bp_wh_2d" down

  2. Verify your .env file has the correct HOST_IP:

    # Check .env file
cat .env

# Ensure HOST_IP is set correctly
HOST_IP=<YOUR_SERVER_IP_ADDRESS>

  3. Restart the services:

    docker compose --profile "bp_wh_2d" up

  4. Verify API_URL in browser console:

    // Open browser console (F12) and check
console.log(window.ENV?.API_URL)

Calibration Issues#

Verification Fails#

Symptom: “Verify Project” button shows error

Possible Causes:

  • Missing required files

  • Invalid alignment data

  • Corrupted video files

  • Server validation error

Solutions:

  1. Check Requirements Checklist

    • ✓ At least 2 videos uploaded

    • ✓ Layout image uploaded

    • ✓ Alignment data uploaded or created

  2. Verify Alignment Data

    • Must have at least 4 complete point sets

    • Each set must have cam0, cam1, and bev points

    • Check JSON format if uploaded manually

  3. Check Video Files

    • Ensure videos are not corrupted

    • Try playing videos locally

    • Re-upload if necessary

  4. Check Server Logs

    # View detailed error messages
docker compose logs | grep -i error

  5. Reset and Retry

    • Go back to previous steps

    • Re-upload files if needed

    • Try verification again

Calibration Fails Immediately#

Symptom: Calibration starts but fails within seconds

Possible Causes:

  • Invalid input files

  • Alignment data errors

  • Server configuration issue

  • Insufficient resources

Solutions:

  1. Check Input Files

    • Verify video files are readable

    • Check layout image is valid

    • Validate alignment data format

  2. Review Alignment Points

    • Ensure points are on ground plane

    • Verify points are visible in all views

    • Check for reasonable spatial distribution

  3. Check Server Resources

    # Check CPU and memory usage
top

# Check GPU availability
nvidia-smi

  4. Check Server Logs

    # View calibration logs
docker compose logs --tail 100

  5. Reset Project

    • Click “Reset Project” button

    • Re-verify and restart calibration

Calibration Takes Too Long#

Symptom: Calibration running for more than 30 minutes

Expected Duration: 5-15 minutes for typical setups

Possible Causes:

  • Large video files

  • Many cameras

  • Server resource constraints

  • Network issues

Solutions:

  1. Check Server Resources

    # Monitor resource usage
htop

# Check GPU utilization
watch -n 1 nvidia-smi

  2. Verify Network Connection

    • Ensure stable connection

    • Check for network interruptions

    • Monitor network traffic

  3. Wait for Completion

    • Calibration may take longer for:

      • High-resolution videos

      • Many cameras (5+)

      • Complex scenes

      • Limited GPU resources

  4. Contact Administrator

    • If exceeds 30 minutes

    • Provide project details

    • Check server configuration

Calibration Completes but Results Look Wrong#

Symptom: Calibration finishes but overlay or projections are incorrect

Possible Causes:

  • Poor alignment point selection

  • Incorrect layout image

  • Camera synchronization issues

  • Scale mismatch

Solutions:

  1. Review Alignment Points

    • Verify points are on ground plane

    • Check spatial distribution

    • Ensure points are visible in all views

    • Add more points (6-8 sets recommended)

  2. Verify Layout Image

    • Check scale and orientation

    • Ensure it matches physical space

    • Verify no distortion or warping

  3. Check Video Synchronization

    • Ensure videos are from same time

    • Verify frame alignment

    • Check for camera movement

  4. Re-run Calibration

    • Delete results

    • Improve alignment points

    • Run calibration again

  5. Try VGGT Refinement

    • If available, run VGGT calibration

    • Compare results with AMC

    • Use better result

Results and Export Issues#

No Results Available#

Symptom: Results step shows “Calibration not complete”

Possible Causes:

  • Calibration not run yet

  • Calibration failed

  • Calibration still running

Solutions:

  1. Check Calibration Status

    • Go to Execute step

    • Check project state

    • Verify calibration completed

  2. Run Calibration

    • If not run, start calibration

    • Wait for completion

    • Return to Results step

  3. Check for Errors

    • If calibration failed, check logs

    • Reset and retry if needed

Export Fails#

Symptom: Export button doesn’t download file

Possible Causes:

  • Browser download settings

  • Popup blocker

  • Server error

  • Insufficient disk space

Solutions:

  1. Check Browser Downloads

    • Verify downloads are allowed

    • Check download folder

    • Look for blocked downloads

  2. Disable Popup Blocker

    • Allow popups for this site

    • Try export again

  3. Check Disk Space

    • Ensure sufficient space on local machine

    • Free up space if needed

  4. Try Different Browser

    • Test in Chrome or Firefox

    • Check if export works

  5. Check Server Logs

    # Check for export errors
docker compose logs | grep -i export

ROI Verification Not Working#

Symptom: “Show ROI & Tripwire Verification” button disabled or fails

Possible Causes:

  • Full Export not generated

  • Missing calibration results

  • Server error

Solutions:

  1. Generate Full Export First

    • Click “Full Export AMC” button

    • Wait for export to complete

    • Try verification again

  2. Verify Calibration Completed

    • Check project state is COMPLETED

    • Ensure results are available

  3. Refresh Page

    • Refresh browser

    • Try verification again

  4. Check Server Logs

    # Check for verification errors
docker compose logs | grep -i "roi_bev"

Performance Issues#

UI is Slow or Unresponsive#

Symptom: UI takes long time to respond to clicks

Possible Causes:

  • Browser performance issues

  • Large files being processed

  • Network latency

  • Server overload

Solutions:

  1. Refresh Browser

    • Close and reopen browser

    • Clear cache and cookies

    • Try again

  2. Close Other Tabs

    • Close unnecessary browser tabs

    • Close other applications

    • Free up system resources

  3. Check Network Latency

    # Ping server to check latency
ping <server-ip>

  4. Check Server Load

    # Monitor server resources
top
htop

  5. Try Different Browser

    • Test in Chrome (recommended)

    • Compare performance

Canvas Rendering is Slow#

Symptom: Drawing or zooming on canvas is laggy

Possible Causes:

  • Large images

  • Browser rendering limitations

  • Hardware acceleration disabled

Solutions:

  1. Enable Hardware Acceleration

    • Chrome: Settings → Advanced → System → Use hardware acceleration

    • Firefox: Preferences → General → Performance → Use hardware acceleration

  2. Reduce Zoom Level

    • Reset to 100% zoom

    • Avoid extreme zoom levels

  3. Use Smaller Images

    • Resize layout image if very large

    • Use appropriate resolution

  4. Upgrade Browser

    • Use latest browser version

    • Consider switching to Chrome

Error Messages#

“Storage limit exceeded”#

Symptom: Error message in browser console

Cause: Browser local storage full

Solution:

  1. Clear browser data:

    • Open browser settings

    • Clear browsing data

    • Select “Cookies and other site data”

    • Clear data

  2. Delete conversation history if using chat features

  3. Refresh page

“Network error”#

Symptom: Error message when performing actions

Cause: Network connectivity issues

Solution:

  1. Check network connection

  2. Verify server is accessible

  3. Check firewall settings

  4. Retry action

“Server error”#

Symptom: Error message with 500 status code

Cause: Backend server error

Solution:

  1. Check server logs for details

  2. Verify server is running properly

  3. Check server resources

  4. Contact administrator if persistent

“Unauthorized”#

Symptom: Error message with 401 status code

Cause: Authentication issue

Solution:

  1. Refresh page

  2. Clear browser cache

  3. Check authentication settings

  4. Contact administrator

“Not found”#

Symptom: Error message with 404 status code

Cause: Resource not found

Solution:

  1. Verify project exists

  2. Check file was uploaded successfully

  3. Refresh project list

  4. Contact administrator if persistent