Troubleshooting
Diagnose and fix common issues. Start with Quick Diagnosis, then jump to the relevant section.
Your SystemUnknown OS • GPU not detected
Quick Diagnosis
- Is the app launching? — No → See App Won't Start
- Is it generating output? — No → See Generation Fails
- Is it slow or producing wrong results? — See Performance Issues
- Is something not downloading? — See Downloads & Models
App Won't Start
| Symptom | Likely Cause | Fix |
|---|---|---|
| Stuck at "Starting..." | Health check URL mismatch | Verify runtime.port and health_check.path in manifest |
| Crashes immediately | Missing Python package | Check Console for ImportError; reinstall app |
| Permission denied | AppImage not executable | chmod +x thumper-run.AppImage |
| Port already in use | Orphan process from previous session | ss -tlnp | grep PORT, then kill the PID |
| Python not found | Missing system Python | Install python3.10+ from your package manager |
| CUDA not available | Wrong PyTorch build | Check patch applies correct CUDA/ROCm torch index |
Generation Fails
| Symptom | Likely Cause | Fix |
|---|---|---|
| Black/NaN images | FP16 overflow on AMD APU | Use BF16 dtype + FP16-fix VAE |
| Out of memory (OOM) | Text encoder + diffusion both on GPU | Set text_encoder_device: cpu in pack manifest |
| Model not found | Wrong install_dir or incomplete download | Re-download from Models page |
| Workflow error (ComfyUI) | Missing custom node | Install missing node via ComfyUI Manager |
| Infinite loading | Model too large for VRAM | Use smaller quantization or split to CPU |
Performance Issues
| Symptom | Likely Cause | Fix |
|---|---|---|
| Slow first generation (AMD) | MIOpen find-db building | One-time ~5 min warmup, then set MIOPEN_FIND_MODE=FAST |
| Slow every generation | --lowvram on APU (shuffles same RAM) | Remove --lowvram flag from patches |
| High memory, GPU at 5% | Tiled VAE on short content | Use non-tiled VAE for content under 60s |
| CPU inference very slow | Expected behavior | Use GPU, or accept 10-50x slowdown vs GPU |
| Model reloads every time | Smart memory disabled | Enable smart memory (default); remove --disable-smart-memory |
NEVER use --lowvram on AMD APU. It does per-layer offload between the SAME physical RAM — 5% GPU utilization, 50× slower.
Downloads & Models
| Symptom | Likely Cause | Fix |
|---|---|---|
| Download stuck at 99% | Corrupted .part file | Delete .part file, retry (auto-resumes from scratch) |
| GPU not detected | Missing or outdated drivers | NVIDIA: nvidia-smi; AMD: rocminfo; Intel: sycl-ls |
| Model shows 0 B size | HF cache ghost repo (aborted download) | Rescan models from Settings; ghost repos are filtered |
| Wrong model loaded | Filename collision in install_dir | Check model path; rename or re-download |
Benchmarks
Reference benchmarks for common tasks. Your results may vary based on system configuration, cooling, and background processes.
Image Generation (SDXL 1024×1024, 20 steps)
| GPU | Time | Notes |
|---|---|---|
| RTX 4090 | ~3.2s | Full CUDA |
| RTX 3060 12GB | ~8.5s | Full CUDA |
| RX 7900 XT | ~5.1s | ROCm 6.2 |
| AMD 780M APU | ~152s | BF16, first run ~188s |
| Apple M2 Max | ~12s | MPS |
| CPU (Ryzen 7) | ~300s | Very slow |
LLM Inference (Qwen3-4B Q4_K_M)
| GPU | Speed |
|---|---|
| RTX 4090 | ~120 tok/s |
| RTX 3060 | ~45 tok/s |
| AMD 780M APU | ~25 tok/s |
| CPU (8-core) | ~8 tok/s |
Music Generation (ACE-Step, 10s track)
| GPU | Time |
|---|---|
| RTX 4090 | ~2s |
| AMD 780M APU | 43s (warm) / 55s (cold) |
Cross-App Performance Reference
Real-world benchmarks across common workloads. Times are for a single generation with warm model cache.
| App | Workload | RTX 4090 | RTX 3060 | RX 7900 XT | AMD 780M | M2 Pro | CPU |
|---|---|---|---|---|---|---|---|
| ComfyUI | SDXL 1024×1024 | ~3s | ~15s | ~6s | ~45s | ~12s | ~180s |
| ComfyUI | LTX Video 5s | ~15s | ~60s | ~25s | N/A | ~45s | N/A |
| Open WebUI | Qwen3 4B (tok/s) | ~120 | ~45 | ~90 | ~15 | ~50 | ~5 |
| ACE-Step | 30s music | ~9s | ~35s | ~15s | ~45s | ~25s | N/A |
| Jan | Llama 3.2 8B (tok/s) | ~110 | ~40 | ~85 | ~12 | ~45 | ~4 |
Agent Tools Reference
The AI assistant has access to 28 tools across 6 categories. Each tool follows a common trait interface.
| Category | Count | Examples |
|---|---|---|
| Launcher | 6 | app_install, app_launch, app_stop, app_uninstall, app_health, process_list |
| GPU Diagnostic | 7 | gpu_detect, vram_report, rocm_check, cuda_check, pytorch_index, npu_list, benchmark |
| Model Intelligence | 5 | model_search, model_download, model_verify, model_link, model_cache_size |
| Manifest v2 | 3 | manifest_validate, manifest_generate, cache_diagnose |
| Diagnostic | 2 | system_info, port_scan |
| Filesystem | 5 | file_read, file_write, file_list, file_search, file_diff |
Tool Trait Interface
rust
#[async_trait]pub trait AgentTool: Send + Sync {fn name(&self) -> &str;fn description(&self) -> &str;fn parameters_schema(&self) -> serde_json::Value;fn is_safe(&self) -> bool;async fn execute(&self, params: Value) -> Result<Value>;}
Invoking Tools
Tools are invoked through the agent chat interface. Type a natural language request and the agent selects appropriate tools. Safe tools run immediately; dangerous tools show a confirmation dialog with the planned action.