Train a concept LoRA on FLUX.2 Klein with AI Toolkit
The Hardware platform column shows where an issue is most relevant. "All hardware platforms" applies to every platform listed in this playbook.
| Symptom | Hardware platform | Cause | Fix |
|---|---|---|---|
| Cannot access gated repo for URL | All hardware platforms | Hugging Face model access restricted or token invalid | Regenerate your Hugging Face token; accept the terms for the FLUX.2 Klein model selected for your system; export a valid HF_TOKEN before download.sh or training |
| "permission denied" when running Docker | All hardware platforms | User not in the docker group | Run sudo usermod -aG docker $USER && newgrp docker |
| Container fails to start with GPU error | All hardware platforms | NVIDIA Container Toolkit not configured | Configure the NVIDIA Container Toolkit for Docker and confirm nvidia-smi works in a GPU container |
| ComfyUI unreachable on port 8188 | All hardware platforms | Container not running or port blocked | Confirm launch_comfyui.sh is running; open http://localhost:8188 or http://<HARDWARE_IP>:8188 |
| Training OOM / memory pressure during train or generate | All hardware platforms | Other GPU jobs, residual cache, or workload exceeds available memory | Stop other GPU processes; bring down ComfyUI before training; flush buffer cache (see note); enable gradient checkpointing or reduce batch size if needed |
| Training appears idle at startup | All hardware platforms | AI Toolkit is downloading the model, caching latents and text embeddings, or compiling the model | Check the console output and allow the startup stage to finish; later runs reuse completed caches |
torch.compile fails | All hardware platforms | A model operation or local compiler dependency is incompatible | Set compile: false in the selected file under config/ and retry |
| ComfyUI cannot find the LoRA | All hardware platforms | The checkpoint is missing or ComfyUI started before it was written | Confirm the .safetensors file exists under models/loras/, then restart ComfyUI |
| Memory pressure within capacity | DGX Spark | UMA buffer cache not released | See UMA note below |
NOTE
Unified memory (UMA). On hardware platforms with unified memory, GPU and CPU share memory dynamically. Some applications have not yet been updated for UMA, so you may hit memory issues even within capacity. If that happens, manually flush the buffer cache:
sudo sh -c 'sync; echo 3 > /proc/sys/vm/drop_caches'
For latest known issues, see the documentation linked under Resources for your hardware platform.