Skip to content

FAQ#

This section describes common video streaming failure scenarios and troubleshooting methods.

Before diagnosing complex scenarios, it is recommended to perform basic checks:

  • Check that your credentials are available and up-to-date;

  • Ensure that the camera URL is correct and accessible from the network where the server is located;

  • Check that the maximum number of connections to the camera itself has not been reached.

If basic checks reveal no issues, but streams continue to disconnect, consider the following typical scenarios.

1․ Problem: The stream is created, but immediately goes into a 'failure' state with a codec initialization error.

Signs of the problem:

  • In the stream's video_info section, all parameters are zero or have default values, indicating no data.

  • The FaceStream logs contain errors such as: initCodec - avcodec_open2 failed! Generic error in an external library, openVideo - initCodec failed!, Stream: ... got error: Couldn't find or init appropriate codec for stream source.

Possible cause:

The video card's hardware decoder (NVDEC) is overloaded. When its usage reaches ~99%, it stops initializing new streams and starts returning errors.

Solution:

  • Enable mixed decoding. To do this, set the mixed_decode parameter in the FaceStream settings. This parameter determines the percentage of streams decoded on the CPU and can range from 0 to 100%. The optimal value is determined experimentally depending on the processor performance and load. Recommended initial values ​​are from 5 to 10, then increased in increments of 5 until the processor can handle the load.

Important! Changing this parameter requires restarting the FaceStream service for the configuration to apply.

  • Check load balancing. Ensure that streams are distributed evenly across all available GPUs. Body detection generates the heaviest load, followed by the combined detection and face detection. This must be taken into account when distributing.

2․ Problem: The stream operates normally for some time, after which it suddenly shuts down.

Signs of the problem:

  • the stream was in the "in_progress" status for a while, then went into "failure";

  • the FaceStream logs contain an error like Interrupt by timeout while reading video frame: 1000 ms..

Possible cause:

The server is unable to receive video data from the camera within the configured timeout. This may be caused by high network load or an unstable network connection to the camera.

Solution: Increase the timeout value. It can be set in the body of the stream creation request ("create stream") in the policies > healthcheck > timeout section. It is recommended to set the value in the range of 3000–10000 ms (3–10 seconds) instead of the default 1000 ms. A good starting point is 3000 ms.

3․ Problem: The stream does not restart automatically after an abnormal termination.

Signs of the problem:

After an error, the stream remains in the "failure" status and does not automatically resume operation, even after a container reboot.

Possible Cause:

  1. The number of restart attempts has been exhausted (if the attempt_count parameter is set and exceeded).
  2. A critical error has occurred that is considered unrecoverable by the system. In this case, an automatic restart will not occur, regardless of the attempt_count value.

Solution:

  • Increase the number of automatic restart attempts. This value can be set in the body of the stream update request ("put stream") in the autorestart > attempt_count section.
  • Recreate the stream manually if the error is critical.

4․ Problem: Error when using nginx as a proxy for requests in LUNA PLATFORM.

Signs of the problem: the FaceStream logs contain an error of the following type:

E1010 16:26:47.672775    40 BodyStreamSender.cpp:59] Track [fdefb8d1-9391-4bd0-8eb2-b16400000054]. Request ID: 1760102807,6950edd9-a3b8-4d39-957a-72ad80d44a6f. Http exception occurred. Error code: system:0 .Reason: `Incorrect Content-Type: must be textual to extract_string, JSON to extract_json.`

At the same time, the nginx logs indicate an error with code 413 (Request Entity Too Large).

Possible Cause: nginx limits the maximum request body size, which results in requests with large data (such as image or video files) being rejected.

Solution:

Increase the maximum allowed request body size (e.g. to 100 MB) in the nginx configuration by adding the parameter:

client_max_body_size 100M;

Example nginx configuration acting as a proxy for the Luna API service.

upstream lunaapi {
   server 127.0.0.1:5000;
}
server {
   listen 6000;
   client_max_body_size 100M;
   location / {        
      proxy_pass http://lunaapi;  
   }
}

After applying the changes, reload the nginx configuration: 

nginx -s reload

5․ Problem: High CPU load when using GPU.

Signs of the problem: In the system resource monitoring, it is clear that the CPU is used at 90-100%, although the threads are configured to be processed on the GPU.

Possible Cause: By default, the numThreads parameter in the runtime configuration is set to -1, which allows FaceStream to use all available CPU threads. This can lead to excessive CPU load.

Solution:

Manually set the optimal number of threads in Runtime settings. To do this:

  • Open the "runtime.conf" configuration file or find the "RUNTIME_CONFIG" section in the LUNA Configurator service;

  • Set the numThreads parameter to a value other than -1.

The optimal value is determined experimentally, depending on the server load and configuration. We recommend starting with a number equal to the number of physical CPU cores minus 2-3 threads (for example, for an 8-core CPU, you can set numThreads = 5).

After applying the settings, monitor for dropped frames. If there are no dropped frames, you can gradually reduce the numThreads value to optimize CPU consumption.