Skip to content

Troubleshooting

Jump to bottom
The Duskfall Portal Crew edited this page Jun 12, 2026 · 1 revision

Troubleshooting

Common issues and their solutions.

Diagnostic Tool

Always run the diagnostic tool before reporting issues:

diagnose.bat      # Windows
./diagnose.sh     # Linux

Output: diagnostics_YYYYMMDD_HHMMSS.txt in the project root. This collects OS version, Python/Node/CUDA versions, nvidia-smi, installed packages, and recent logs. Attach this file to any GitHub issue.

Common Issues

Python Not Found

'python' is not recognized as an internal or external command
  • Windows: Reinstall Python with "Add to PATH" checked, or add manually via System Properties → Environment Variables
  • Linux: sudo apt install python3.10 python3.10-venv python3-pip
  • Verify: python --version

CUDA Not Available

torch.cuda.is_available()  # returns False
  1. Check nvidia-smi — if it fails, drivers aren't installed
  2. Verify CUDA version ≥ 12.1 in nvidia-smi output
  3. Check PyTorch CUDA: python -c "import torch; print(torch.version.cuda)"
  4. If PyTorch reports CPU-only, reinstall: pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

npm Install Fails

npm ERR! ERESOLVE unable to resolve dependency tree

Clear cache and retry:

npm cache clean --force
npm install

Permission Denied (Windows)

  • Do NOT install in C:\, Program Files, OneDrive, Dropbox, or Google Drive
  • Install in a path you own: C:\Users\YourName\Projects\

Permission Denied (Linux)

chmod +x install.sh start_services_local.sh restart.sh

Port Already in Use

# Windows — find and kill process on port 3000
netstat -ano | findstr :3000
taskkill /PID <pid> /F

# Linux — find and kill
lsof -ti:3000 | xargs kill -9

Or use a different port:

start_services_local.bat --port 4000 --backend-port 9000

Training Fails Immediately

  1. nvidia-smi — verify GPU is detected
  2. nvidia-smi --query-gpu=memory.free,memory.total --format=csv — check VRAM
  3. Check logs/app_YYYYMMDD.log for error details
  4. Run the diagnostic tool
  5. Open a GitHub issue with the diagnostic output

VastAI: Services Not Starting After Reboot

Supervisor manages the services. Check status:

supervisorctl status
supervisorctl restart all

node_modules in Project Root (Windows)

If you see node_modules/ in the project root (not in frontend/), it was created by a shadcn CLI command running in the wrong directory. It is safe to delete.

Training Logs Freeze Mid-Run

Logs should stream in real time. If they appear frozen:

  • The log poller uses a total_lines_written counter (not a fragile deque-relative index)
  • PYTHONUNBUFFERED=1 and the -u flag ensure stdout streams
  • Try switching browser tabs and back — the visibility-aware poller should re-sync

NaN Loss During Training

NaN loss commonly occurs with:

  • CAME optimizer with fp16 — use bf16 instead
  • CAME with conservative preset — was fp16 + conv_dim: 32; fixed to bf16 + conv_dim: 0
  • Very short prompts — SDXL NaN loss root cause was a CLIP mask bug (fixed upstream)

Reporting a Bug

When opening a GitHub Issue:

  1. Run the diagnostic tool and attach the output
  2. Include:
    • Your OS and deployment mode (local/cloud)
    • GPU model and VRAM
    • Python and Node.js versions
    • Error output / logs
    • Steps to reproduce
    • Training config (sanitized of personal paths)

Maintenance Scripts

clean_slate.py

Use when the install is in a broken state that reinstalling hasn't resolved:

python clean_slate.py --dry-run    # Preview
python clean_slate.py              # Remove build artifacts, .venv, node_modules
python clean_slate.py --nuclear    # Also remove models, datasets, outputs

After running, re-run the installer.

Still Stuck?

Clone this wiki locally