Troubleshooting

This page covers common issues you may encounter when deploying and running the CE.SDK Renderer, along with solutions and diagnostic steps.

Verifying Your Environment#

Before debugging specific issues, verify that your server meets all requirements by running our GPU requirements checker script inside your deployment environment (not inside the container). Download check-requirements.sh and run it:

bash check-requirements.sh

The script checks for:

• NVIDIA driver and GPU detection
• NVENC hardware encoder availability
• EGL context support (required for GPU-accelerated rendering)
• Required system libraries
• Docker GPU runtime configuration

All items marked with a red X need to be addressed before the Renderer can use GPU acceleration. See the Server setup guide for installation instructions.

Reproduction baseline#

Our live demo is powered by a reference deployment of the CE.SDK Renderer. You can upload your scene or archive there to compare results against a known-good baseline before investigating further.

GPU and Rendering Issues#

GPU is not being used for rendering#

Symptoms: Exports are significantly slower than expected, or verbose logs show falling back to CPU rendering.

Possible causes and solutions:

• Missing --runtime=nvidia flag: When using docker run, you must pass both --runtime=nvidia and --gpus all. Using only --gpus all is not sufficient.

  # Correct
  sudo docker run --runtime=nvidia --gpus all ...
  
  # Incorrect - GPU will not be available for rendering
  sudo docker run --gpus all ...

• Missing runtime: nvidia in Docker Compose: When using Docker Compose, add runtime: nvidia to your service configuration:

  services:
    renderer:
      image: docker.io/imgly/cesdk-renderer:1.83.0
      runtime: nvidia
      deploy:
        resources:
          reservations:
            devices:
              - driver: nvidia
                count: all
                capabilities: [gpu]

• NVIDIA Container Runtime not installed or configured: Run the requirements checker script to verify. If missing, install the NVIDIA Container Toolkit and configure the runtime:

  sudo nvidia-ctk runtime configure --runtime=docker
  sudo systemctl restart docker

• Kubernetes / containerd environments: If you’re using containerd instead of Docker, ensure the NVIDIA device plugin is installed and your pod spec requests GPU resources. The docker and nvidia-container-runtime checks from the script may show failures, which is expected in a Kubernetes environment.

EGL context creation failure#

Error: Error encountered while creating an EGL hardware-accelerated context, falling back to CPU rendering: EGL initialize error: UNKNOWN

This means the Renderer could not create a hardware-accelerated OpenGL context. The Renderer will still work but will fall back to CPU rendering, which is significantly slower for video exports.

• Verify the NVIDIA driver is installed on the host: nvidia-smi
• Verify the NVIDIA EGL libraries are available: check for libEGL_nvidia.so and the vendor config at /usr/share/glvnd/egl_vendor.d/10_nvidia.json
• Ensure the container has GPU access (see above)
• If running on a machine without a GPU, this message is expected. Image exports will work but be slower, and video exports depend on available CPU resources.

Forcing GPU-only rendering for validation#

To verify GPU acceleration is working correctly, pass --render-device gpu to the Renderer. This will cause the export to fail if GPU acceleration is unavailable, rather than silently falling back to CPU:

sudo docker run --runtime=nvidia --gpus all \
  docker.io/imgly/cesdk-renderer:1.83.0 \
  --render-device gpu \
  -i /input/scene.scene -o /output/result.mp4

If this command fails, your GPU setup needs to be fixed before you can benefit from GPU acceleration.

Video Encoding Performance#

Video exports are slower than expected#

The CE.SDK Renderer uses the CPU for video encoding by default, because CPU encoding supports higher output bitrates than GPU-based NVIDIA NVENC encoding.

Key factors that affect encoding performance:

If exports are taking much longer than expected:

1. Check that GPU rendering is active: The EGL fallback warning is always printed to the output when GPU acceleration is unavailable. If you see it, GPU rendering is not being used.

2. Compare against the baseline: Export the same scene using our live demo to establish a reference time.

3. Consider your CPU power: If your instance has few CPU cores, CPU-based encoding at high bitrates will be slow. Options:

   • Use an instance with more CPU cores
   • Force GPU-based encoding (bitrate limited by resolution, see below)
   • Lower the requested output bitrate

Forcing GPU-based video encoding#

You can force the Renderer to use the GPU for H.264 encoding by setting the UBQ_AV_OVERRIDE_H264_ENCODER environment variable. This speeds up encoding but limits the maximum output bitrate depending on the output resolution, due to NVIDIA NVENC hardware constraints:

sudo docker run --runtime=nvidia --gpus all \
  -e UBQ_AV_OVERRIDE_H264_ENCODER=vulkanh264enc \
  docker.io/imgly/cesdk-renderer:1.83.0 \
  -i /input/scene.scene -o /output/result.mp4

sudo docker run --runtime=nvidia --gpus all \
  -e UBQ_AV_OVERRIDE_H264_ENCODER=fluhwvanvench264enc \
  docker.io/imgly/cesdk-renderer-avlicensed:1.83.0 \
  -i /input/scene.scene -o /output/result.mp4

Choosing between CPU and GPU encoding#

Video Decoding Issues#

Export fails with VIDEO_DECODING_UNSUPPORTED or the output video is green#

Symptoms: The export fails with a VIDEO_DECODING_UNSUPPORTED error, or the export completes but the video content renders as green/glitched frames while the audio is correct.

Cause: An input video uses an H.264 profile the Renderer cannot decode. The Renderer supports H.264 input with 8-bit 4:2:0 chroma subsampling (yuv420p) — the format produced by virtually all cameras, phones and editing tools. Profiles such as High 4:4:4 Predictive or 10-bit inputs (e.g. yuv444p10le) are not supported: the open-source codec set rejects them with VIDEO_DECODING_UNSUPPORTED, and the licensed codec set may produce corrupted (green) output. Browsers can decode these profiles, so the same scene may export fine in the CE.SDK web editor.

Diagnosis: Check the pixel format and profile of your input videos:

ffprobe -v error -select_streams v:0 \
  -show_entries stream=codec_name,profile,pix_fmt \
  -of default=noprint_wrappers=1 input.mp4

If pix_fmt is anything other than yuv420p, transcode the file before importing:

ffmpeg -i input.mp4 -c:v libx264 -pix_fmt yuv420p -c:a copy output.mp4

Licensed Codec Issues#

Open-source vs. licensed codec differences#

For details, see the Licensed codec setup page.

Asset Issues#

Export fails with FILE_FETCH_FAILED for a font#

An older scene stores the font file name that the asset version of its time shipped, for example /ly.img.typeface/fonts/Manrope/Manrope-Regular.ttf. Newer asset versions ship that font as .woff2, so the stored name no longer exists in the bundled tree.

The Renderer registers the asset sources of the directory given by --base-path and replaces such a name with the file that the tree ships. This works only for a local directory, because a URL cannot be listed. If you point --base-path at an assets server, host the asset version that the scene was made with, or open and save the scene once in the editor to refresh the stored names.

Container and Deployment Issues#

Container fails to start#

• Image not found: Verify you are pulling the correct image name and tag. Licensed codec images require authentication:

  sudo docker login container.img.ly -u "oauth" -p "YOUR-API-KEY"

• Architecture mismatch: The CE.SDK Renderer is built for x86_64 (AMD64) Linux only. ARM-based instances (e.g. AWS Graviton) are not supported.

Using containerd instead of Docker#

If your environment uses containerd (common in Kubernetes), the Docker-specific checks from the requirements script will fail. This is expected. Ensure:

• The NVIDIA device plugin for Kubernetes is installed
• Your pod spec requests nvidia.com/gpu resources
• The container runtime is configured to use the NVIDIA runtime class

Getting Help#

If you’ve verified your environment, compared results against the baseline, and still encounter issues:

1. Run the requirements checker script and include the output
2. Include the --verbose logs from the Renderer
3. Note the Renderer container version and variant you’re using
4. Contact support at support@img.ly