Troubleshooting

Common issues and solutions for StreamDiffusionTD v0.4.0 installation and operation.

For a pasteable single-issue URL, use FAQ search instead of an anchor on this page. Cold loads of this page do not keep # anchors.

v0.4.0 upgrade

  • v0.3.1 to v0.4.0: load the new tox, Install Step 1, take Full Update. This rebuilds the venv (torch 2.11, TensorRT 10.16). Restart TouchDesigner after.
  • v0.4.0 beta: same, plus delete engines/td/ before first run
  • First ControlNet stream rebuilds its engine once. Expected.
  • Full Update refused: that folder’s git origin is a fork. Use Fresh Install (New Location)
  • Restart TD after install so cuda-link sees CUDALINK_LIB_PATH
  • Full steps: Installation Guide

First Step: Use the Installer CLI

v0.3.1 includes a built-in installer CLI with tools for diagnosing and fixing common issues. Activate the venv from the Install page and run:

cd StreamDiffusion-installer
python -m sd_installer verify    # 13-point environment check
python -m sd_installer repair    # auto-fix common dependency issues
python -m sd_installer diagnose  # full system info dump for bug reports

The verify command checks PyTorch CUDA, StreamDiffusion core, numpy, diffusers fork, protobuf, onnx, peft, and more. The repair command fixes the most common issues automatically.

Installation Issues

No Console Window During Install

Symptom: You pulse an install step, no command window opens, and nothing reports progress. The install folder does keep growing in size. Affects: v0.2.x (including v0.2.99) on TouchDesigner 2025. Cause: TouchDesigner 2025 changed how child processes get a console. A subprocess now has to request its own console window or it runs hidden. v0.2.x does not request one, so the install is genuinely running, you just cannot see it. Solution: Move to v0.4.0. v0.3.1 and later request a new console on TD 2025, so the window comes back. On v0.2.x the only alternatives are watching the folder size until it stops growing, or running TouchDesigner 2023.

Python Not Found

Error: “Python not found” or installation fails Solution:

  • Install Python 3.11.9 from python.org
  • Ensure “Add to PATH” is checked during installation
  • Restart TouchDesigner after Python installation
  • Important: Python 3.12 and 3.13 are NOT supported

“cudart” Import Error

Error: cannot import name 'cudart' from 'cuda' (unknown location) Context: Reported on RTX 5070 with CUDA 12.8 selected

  • May need specific CUDA toolkit version
  • Not clearly resolved. Check Discord for updates

“polygraphy” Module Missing

Error: ModuleNotFoundError: No module named 'polygraphy' Solution: You skipped installing TensorRT. Click the “Install TensorRT” button on the Install page.

Folder Naming Conflict

Error: Import failed: no module named 'streamdiffusion.config' Solution: Don’t name your installation folder “streamdiffusion”. This conflicts with the Python module. Use a different name like “StreamDiff031” or “SD_v031”.

Virtual Environment Creation Failed

Error: Installation hangs or venv creation fails Solution:

  • Delete the venv folder in your installation directory
  • Run installation again
  • Avoid spaces in the base folder path
  • Windows: Do not use Microsoft OneDrive locations
  • Check antivirus isn’t blocking Python

flash-attn Crash

Error: Pipeline crashes on import with flash-attn related errors Solution: If you have flash-attn installed, uninstall it:

pip uninstall flash-attn

OpenCV INTER_AREA Error

Error: AttributeError: module 'cv2' has no attribute 'INTER_AREA', with a traceback ending in controlnet_aux/midas/midas/transforms.py. The server stops during initialization.

Cause: opencv 4.13 and newer are built against numpy 2.x. v0.3.1 pins numpy to 1.26.4 because StreamDiffusion and mediapipe both break on numpy 2. When the newer opencv loads against the older numpy the module only partly initializes, so constants like INTER_AREA are never created and controlnet_aux fails on import.

This is usually caused by installing OpenCV packages manually while troubleshooting something else. A clean v0.3.1 install pins opencv to 4.8.1.78 on its own.

Solution: Re-run the installer. This does not wipe your venv or re-download models, it re-runs the install phases, one of which removes conflicting opencv variants and reinstalls the pinned version.

cd \StreamDiffusion
venv\Scripts\activate
python -m sd_installer install --cuda cu128

Or fix opencv on its own if you don’t want the full re-run:

pip uninstall opencv-python opencv-python-headless opencv-contrib-python -y
pip install --no-deps opencv-python==4.8.1.78

The --no-deps matters. Without it pip can pull numpy 2 back in and you end up where you started.

Confirm the fix took:

python -c "import cv2, numpy; print(cv2.__version__, numpy.__version__, cv2.INTER_AREA)"

Expect 4.8.1.78 1.26.4 3.

Two notes: repair does not currently fix this one, use a command above instead. And verify will report both StreamDiffusion core and controlnet_aux as failed from this single cause, because StreamDiffusion imports controlnet_aux. One fix clears both, don’t chase them separately.

v0.3.0 Fix Scripts Breaking v0.3.1

Problem: Running the v0.3.0 Fix_All_Dependencies.bat on a v0.3.1 install overwrites the required varshith15 diffusers fork with vanilla diffusers, breaking kvo_cache and cached attention. Solution: Run python -m sd_installer repair to reinstall the correct diffusers fork.

Version Conflicts Between Installations

Error: Features missing or unexpected behavior Solution: v0.3.1 MUST be installed in a separate folder from v0.2.99 and v0.3.0. Do not upgrade in place.

RTX 50-Series Specific Issues

General 50-Series Issues

  • Use v0.4.0. 50-series cards need CUDA 12.8 and TensorRT 10.16, the first TensorRT release with production Blackwell support on Windows. v0.4.0 installs both
  • CUDA 12.8 is required (not optional). v0.4.0 offers no other choice, so there is nothing to pick in the UI
  • Do not fall back to v0.2.x on a 50-series card. This page used to suggest trying v0.2.99 when a 50-series install got stuck. That advice is out of date and now causes a second problem of its own: on TouchDesigner 2025, v0.2.x runs its install with no visible console. See No Console Window During Install
  • TensorRT engine builds take longer than on 40-series. The first ControlNet stream rebuilds its engine once, which is expected
  • Seeing cv2 has no attribute 'INTER_AREA'? That is not a 50-series problem, it is an opencv/numpy conflict common on CUDA 12.8 installs. See OpenCV INTER_AREA Error above

5070/5070 Ti Issues

  • Works on v0.4.0 + CUDA 12.8
  • The older “mixed success” reports were on v0.2.x and v0.3.0, before the CUDA 12.8 and TensorRT 10.16 stack landed. Retest on v0.4.0 before assuming the card is the problem
  • If an earlier attempt left a broken venv behind, take Fresh Install (New Location) rather than repairing in place

5090 Issues

  • Works on v0.4.0 + CUDA 12.8
  • Engine build time may be longer than expected
  • TensorRT 10.16 also clears an FP8 performance regression that affected Blackwell on TensorRT 10.12 and 10.13

Runtime Issues

“Acceleration Has Failed”

Error: Exception: Acceleration has failed Solutions:

  1. Delete the engines folder at StreamDiffusion/engines/td/
  2. Ensure IP Adapter is OFF when using sd-turbo (not compatible)
  3. Restart stream
  4. If persists, try without TensorRT acceleration first

Low FPS Performance

Symptoms: Generation is very slow Solutions:

  • Enable TensorRT acceleration (set Acceleration to “tensorrt”)
  • Reduce resolution to 512x512
  • Lower step count (1-2 steps)
  • Use stabilityai/sd-turbo instead of SDXL
  • Disable IP Adapter
  • Set ControlNet weight to 0
  • Use depth_tensorrt instead of depth for ControlNet preprocessing (60% faster, much less VRAM)

FPS Degradation Over Time

Symptoms: FPS starts high then drops after a few minutes Solutions:

  • Restart the stream periodically
  • Restart TouchDesigner
  • Report to Discord with specifics

Memory Issues / CUDA Out of Memory

Error: “CUDA out of memory” or crashes Solutions:

  • Use “Unload Models” pulse to free VRAM
  • Close other GPU-intensive applications
  • Reduce resolution
  • Disable IP Adapter
  • Use sd-turbo instead of SDXL
  • Restart TouchDesigner
  • Check the VRAM budget table for expected usage

TouchDesigner Crashes on Start Stream

Solutions:

  • Check numpy version compatibility
  • Verify CUDA is properly installed
  • Try disabling TensorRT first
  • Check command window for specific error

Black Frames

Possible causes:

  • Prompt weights summing to zero (NaN propagation). Ensure at least one prompt weight is above 0
  • IP Adapter enabled with sd-turbo (incompatible)
  • Stale error from previous session (restart stream to clear)

Model & Feature Issues

IP Adapter Not Working

Error: IP Adapter has no effect Solutions:

  • IP Adapter must be enabled BEFORE starting stream
  • IP Adapter doesn’t work with sd-turbo (SD 2.1 architecture)
  • Use SDXL-Turbo or SD 1.5 based models
  • Verify IP Adapter Scale is above 0

ControlNet Not Working

Error: ControlNet has no effect on output Solutions:

  • ControlNet must be enabled before starting stream
  • Check ControlNet weight is above 0
  • Ensure ControlNet model matches base model architecture:
    • SDXL model needs SDXL ControlNets
    • SD 1.5 model needs SD 1.5 ControlNets
  • Verify input is connected to second input (local mode)
  • Check that Autopreprocess isn’t overriding your manual preprocessor selection

LoRA Not Working

Error: LoRA doesn’t affect output Solutions:

  • sd-turbo is based on SD 2.1 so SD 1.5 LoRAs won’t work
  • SDXL-Turbo needs SDXL LoRAs
  • LoRA must be enabled before starting stream

Models Won’t Load

Error: “Failed to load model” or black output Solutions:

  • Verify model path or HuggingFace ID is correct
  • Check internet connection for first-time downloads
  • Try stabilityai/sd-turbo (known working model)
  • Clear HuggingFace cache and re-download

StreamV2V Not Working

Error: Cached attention has no effect or crashes Solutions:

  • TensorRT acceleration is required (non-TRT paths broken)
  • Resolution is locked to engine build dimensions. If you changed resolution, rebuild the engine
  • Ensure peft package is installed (python -m sd_installer verify checks this)
  • Must be enabled before starting the stream

TensorRT Issues

Engine Build Takes Forever

Info: First-time engine build can take 20-30+ minutes Solutions:

  • This is normal for first build
  • Don’t interrupt the process
  • Subsequent starts will be fast (engines cached)

Engine Rebuild Required

TensorRT engines need rebuild when changing:

  • Model
  • IP Adapter enabled/disabled
  • ControlNet enabled/disabled

Engines do NOT need rebuild for:

  • Resolution changes (384-1024px)
  • Step count changes

Exception: StreamV2V engines are locked to build resolution.

Depth TRT Preprocessor Build

The depth_tensorrt preprocessor auto-builds its TRT engine on first use (~2 minutes on a 4090). This is a one-time build. If it fails, check that your onnx version is correct (python -m sd_installer verify).

Dependency Reference

If you hit import errors or build failures, these are the version pins v0.3.1 expects:

PackageRequirementWhy
numpybelow 2.0SD and mediapipe break on numpy 2.x
protobuf4.25.8 (below 5.0)6.x breaks mediapipe serialization
opencv-python4.8.1.78 (below 4.13)4.13+ requires numpy 2+
onnx1.18.01.20+ removes float32_to_bfloat16, crashes engine builds
peft0.6.0+Required for StreamV2V / cached attention
diffusersvarshith15 forkMust be the fork, not vanilla. The installer handles this

Run python -m sd_installer repair to auto-fix numpy, protobuf, onnx, peft, mediapipe, and the diffusers fork.

opencv is the exception. repair does not currently handle it and will report “No known issues detected” even when opencv is the problem. If opencv is your issue, see OpenCV INTER_AREA Error under Installation Issues, or re-run python -m sd_installer install which re-applies the pin.

Daydream Cloud Issues

Connection Failed

Error: Cannot connect to Daydream backend Solutions:

  • Hit the Daydream Login pulse on the Install page (there is no API key field)
  • Check internet connection
  • Try restarting the connection

High Latency

Solutions:

  • Cloud processing has inherent latency
  • Check internet speed
  • Try different times of day

Note: Daydream ships with v0.2.2 (v0.2.3 was skipped due to a stability issue). V2V on cloud is deferred to Daydream v0.2.4.

General Troubleshooting Steps

  1. Run the installer CLI: python -m sd_installer verify then repair
  2. Check Command Window: Always check for detailed error messages
  3. Enable Debug Mode: Turn on Debug in Settings 2 for more logging
  4. Restart Stream: Stop and restart the stream
  5. Restart TouchDesigner: Many issues resolve with a fresh start
  6. Delete Engines: Remove StreamDiffusion/engines/td/ folder
  7. Clean Reinstall: Delete entire installation folder and reinstall

Getting Help

  • Discord: Best way to get help. Post in #troubleshoot-central or #streamdiffusiontd
  • Search Discord: Many issues are already documented
  • When reporting, include:
    • GPU model and VRAM
    • Output from python -m sd_installer diagnose (copies to clipboard)
    • StreamDiffusionTD version
    • Error messages from command window
    • Screenshots if helpful