Troubleshooting

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

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

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

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

  • CUDA 12.8 is required (not optional)
  • Some users report needing multiple installation attempts
  • TensorRT may take longer to build engines
  • If stuck, try v0.2.99 which some users report works better

5070/5070 Ti Issues

  • Mixed success reports
  • Ensure CUDA 12.8 is selected during installation
  • May need to delete venv folder and reinstall

5090 Issues

  • Generally works with v0.3.1 + CUDA 12.8
  • Engine build time may be longer than expected

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-pythonbelow 4.134.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 most of these issues.

Daydream Cloud Issues

Connection Failed

Error: Cannot connect to Daydream backend Solutions:

  • Verify API key is correct
  • 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