Troubleshooting#

This page provides comprehensive support and troubleshooting information for the Smart Intersection Sample Application. It is divided into the following sections:

  • Common Issues: General troubleshooting steps for resolving issues like container failures, port conflicts, and missing dependencies.

  • Troubleshooting Docker Deployments: Steps to address problems specific to Docker deployments.

If you encounter any problems with the application not addressed here, check the GitHub Issues board. Feel free to file new tickets there (after learning about the guidelines for Contributing).

1. Common Issues#

1.1 Containers Not Starting#

  • Issue: The application containers fail to start.

  • Solution:

    docker compose logs
    

    Check the logs for errors and resolve dependency issues.

1.2 Port Conflicts#

  • Issue: Port conflicts with other running applications.

  • Solution: Update the ports section in the Docker Compose file.

1.3 Missing Dependencies#

  • Issue: Required software dependencies are not installed.

  • Solution:

    sudo apt-get install -y <dependency>
    

1.4 Camera Stream Stuck#

  • Issue: Camera Streams seem to be stuck when Scenescape UI is accessed with localhost URL.

  • Solution: Make sure to access the localhost URL ONLY via RDP/VNC sessions. Opening via browser extensions from a remote machine is NOT recommended.

1.5 Inaccurate detections seen when running the NPU inference pipeline on ARL and MTL NPUs#

This is a known issue.

1.6 NPU Inference Failures with Geti-Trained Models#

  • Issue: If you experience errors or failures when running an NPU workload with a model trained in Intel Geti, this may be caused by Non-Maximum Suppression (NMS) being embedded within the model graph. The NPU does not support dynamic shapes, and NMS operations with dynamic output shapes are incompatible with NPU execution.

  • Solution: Follow the Export and Optimize Geti Model guide to generate a model with NMS removed from the model graph. NMS will then be handled by DL Streamer.

1.7 Application Fails to Start in Air-Gapped (No Internet) Environments#

  • Issue: When running the application on a machine without internet access, containers fail to start with errors like failed to resolve reference, or Grafana dashboards show “No data” even though containers appear healthy.

  • Solution: While internet is still available, run the following preparation steps after ./install.sh smart-intersection:

    # Pre-install Node-RED InfluxDB plugin into the named volume
    docker compose run --rm --no-deps --entrypoint "npm" node-red install node-red-contrib-influxdb
    
    # Pre-pull all container images
    docker compose pull
    

    After disconnecting from the Internet,

    • Export admin password as environment variable:

      export SUPASS=$(cat ./smart-intersection/src/secrets/supass)
      
    • Start the application with proxy variables(if any) unset:

      unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY no_proxy NO_PROXY
      docker compose up -d
      

2. Docker Deployments#

2.1 Containers Failing To Start#

  • Check the Docker logs for errors:

    docker compose logs
    

2.2 Port Conflicts#

  • Update the ports section in the Compose file to resolve conflicts.

2.3 Reset Application#

  • Follow these steps to reset the application to the initial state

    docker compose down
    docker volume ls | grep metro-vision-ai-app-recipe | awk '{ print $2 }' | xargs docker volume rm
    

2.4 Cleanup secrets#

  • Follow these steps to re-generate the secrets:

    rm ./src/secrets/browser.auth
    
  • Then repeat Step 2 Setup Credentials and Download Assets in Get Started

2.5 Cannot access application in remote host#

  • Update the firewall to receive request to port 443

    sudo ufw allow 443/tcp
    
  • Stop other services that might be running in port 443 (e.g. Kubernetes Load Balancer)

2.6 Services scene or web fails to start#

  • On first starts, scene or web might fail to start due to a timeout on waiting for pgserver initialization to be ready. Restart the services with:

    docker compose up -d scene web
    

2.7 Grafana shows No data when accessed remotely#

  • This issue occurs when there is a time synchronization mismatch between the system running the application and the system accessing Grafana through a browser. Grafana relies on timestamps to display data, and if the clocks on the two systems are not synchronized, it may result in no data being shown.

  • Use Grafana’s time range filter to adjust the displayed time range. Set it to match the timestamp of the data being generated by the application. This ensures that the data falls within the selected time range and becomes visible in the dashboard.

  • This adjustment is particularly useful when the systems are in different time zones or have slight clock differences

2.8 Application UI shows No objects detected on scene#

  • This issue occurs when the scene controller is unable to establish a connection with the message broker. Ensure that the broker service is running and accessible, and verify the network configuration to allow communication between the scene controller and the broker.

  • Inspect the logs of the scene controller with:

    docker compose logs scene
    
  • When the scene controller can’t connect to the broker, the following log lines are shown:

    Starting scene controller
    Broker broker.scenescape.intel.com online: [Errno 111] Connection refused
    Broker broker.scenescape.intel.com online: [Errno 111] Connection refused
    Broker broker.scenescape.intel.com online: Connecting
    
  • To address this issue, restart the scene controller:

    docker compose down scene
    docker compose up -d scene
    
  • Then verify that the container is ready:

    Broker broker.scenescape.intel.com online: Connecting
    Broker broker.scenescape.intel.com online: 0
    Took 1 seconds
    Container is ready
    
  • Now the Application UI should show objects detected on scene.

2.9 Accessing the MQTT Broker Externally#

  • Issue: You want to connect an external MQTT client to the broker for debugging or monitoring topics.

  • Solution: Expose port 1883 on the broker service by adding a ports section in docker-compose.yml:

    broker:
      ports:
        - "1883:1883"
    
  • Then restart the broker:

    docker compose up -d --force-recreate broker
    
  • Connect using an MQTT client with TLS and the CA certificate:

    mosquitto_sub -h <HOST_IP> -p 1883 \
      --cafile ./smart-intersection/src/secrets/certs/scenescape-ca.pem \
      -t '#' -v
    

    Note

    The broker uses TLS (TLSv1.3) but allows anonymous connections — no username/password is required. You must use an MQTT client (not a web browser) since MQTT is a TCP protocol, not HTTP.