Common Issues

Troubleshooting guide for 360 Hextile common problems

Last updated: 2026-01-01

Common Issues

This guide covers the most frequently encountered issues and their solutions.

Installation Issues

Python Version Error

Error: Python 3.8 or higher required

Solution:

# Check Python version
python --version

# Install Python 3.8+ from python.org
# Or use pyenv:
pyenv install 3.10.0
pyenv global 3.10.0

CUDA Not Found

Error: CUDA not available or CuPy import failed

Solutions:

  1. Install CUDA Toolkit
  2. Download from NVIDIA: https://developer.nvidia.com/cuda-downloads
  3. Version 11.x or 12.x recommended

  4. Restart after installation

  5. Verify Installation bash nvidia-smi # Should show GPU info and CUDA version

  6. Install CuPy bash pip install cupy-cuda11x # Replace with your CUDA version

Node.js Issues

Error: npm command not found

Solution:

# Use local Node.js (no global install needed)
scripts\setup_node_local.bat

# Or install globally from nodejs.org

Processing Issues

Out of Memory Error

Error: CUDA out of memory or RuntimeError: CUDA error

Solutions:

  1. Use Smaller Template
  2. Switch from 44_4K → 32_3K → 20_2K

  3. Reduces VRAM requirements

  4. Use Sequential Mode

  5. Instead of Batch mode
  6. Processes one tile at a time

  7. Lower VRAM usage

  8. Close Other Applications ```bash # Check GPU usage nvidia-smi

# Close Chrome, games, other GPU apps ```

  1. Reduce Batch Size
  2. In configuration, set smaller batch
  3. Trade speed for memory

Processing Stalls

Symptom: Processing freezes at specific tile

Solutions:

  1. Check GPU Temperature bash nvidia-smi # If >85°C, thermal throttling may occur

  2. Restart Backend ```bash # Stop API server Ctrl+C

# Restart python backend/api/main.py ```

  1. Clear GPU Memory python import cupy as cp cp.get_default_memory_pool().free_all_blocks()

Seams Visible in Output

Symptom: Visible lines between tiles in final image

Causes & Solutions:

  1. Strength Too High
  2. Reduce strength from 0.7 → 0.3-0.5

  3. Less AI modification = better blending

  4. Wrong Template

  5. Ensure using correct template for input

  6. Verify template files are complete

  7. Inpaint Masks Missing

  8. Check templates/*/masks/ folder
  9. Re-download template if corrupted

Poor Quality Results

Symptom: Output looks worse than input

Solutions:

  1. Adjust Strength
  2. Too low (< 0.2): Barely any change
  3. Too high (> 0.8): Over-processed

  4. Sweet spot: 0.3-0.5

  5. Improve Prompt Bad: "better" Good: "photorealistic, enhanced details, vibrant colors"

  6. Increase Steps

  7. From 20 → 40-50

  8. More diffusion iterations = better quality

  9. Check Input Quality

  10. Input must be high resolution
  11. Minimum 4096x2048 for best results

Upload Fails

Error: Failed to upload image

Solutions:

  1. Check File Format
  2. Only JPG and PNG supported

  3. Convert from other formats first

  4. Reduce File Size

  5. Max 100MB by default

  6. Compress or resize if needed

  7. Verify API Running bash # Check API is accessible curl http://localhost:8000/api/templates/

WebSocket Connection Failed

Error: WebSocket disconnected or no progress updates

Solutions:

  1. Check API Server
  2. Ensure backend running

  3. Look for errors in console

  4. Firewall

  5. Allow port 8000

  6. Disable firewall temporarily to test

  7. Application Console

  8. Open DevTools (if in dev mode)
  9. Check Console tab for errors

Application Won't Start

Error: Application fails to launch

Solutions:

# Clean and reinstall
cd frontend
rm -rf node_modules
rm package-lock.json
npm install
npm run tauri:dev

Application Issues

App Won't Launch

Symptom: Click icon, nothing happens

Solutions:

  1. Install WebView2 bash winget install Microsoft.EdgeWebView2Runtime

  2. Check Logs

  3. Open application logs directory

  4. Look for error messages

  5. Run in Development Mode

  6. Try npm run tauri:dev to see error output

GPU Not Detected

Error: No CUDA-capable device found

Solutions:

  1. Update Drivers
  2. Download from NVIDIA
  3. Install latest drivers

  4. Restart

  5. Check GPU bash nvidia-smi # Should show your GPU

  6. CUDA Toolkit

  7. Ensure CUDA installed
  8. Add to PATH if needed

Performance Issues

Slow Processing

Symptom: Takes much longer than expected

Diagnosis:

# Monitor GPU usage
nvidia-smi -l 1

# Check if GPU at 100% utilization
# If not, check:

Solutions:

  1. GPU Throttling
  2. Check temperature (should be < 80°C)

  3. Improve cooling/ventilation

  4. CPU Bottleneck

  5. Close background applications

  6. Use faster storage (SSD)

  7. Diffusion Settings

  8. Reduce steps (50 → 30)
  9. Lower guidance scale
  10. Use smaller template

High Memory Usage

Symptom: System runs out of RAM

Solutions:

  1. Increase Virtual Memory
  2. Windows: Settings → System → About → Advanced system settings

  3. Set to 16GB+

  4. Close Applications

  5. Browser tabs

  6. Other programs

  7. Use 64-bit Python bash python --version # Should show 64-bit

Error Messages

"Template not found"

Cause: Missing or incorrect template name

Solution:

# List available templates
ls resources/templates/

# Use exact name from list
# Case-sensitive: "Hextile_32_3K" not "hextile_32_3k"

"Invalid image dimensions"

Cause: Image not equirectangular (2:1 ratio)

Solution: - Check dimensions (width should be 2× height) - Valid: 4096×2048, 8192×4096 - Invalid: 1920×1080, 2048×2048

"Diffusion model not found"

Cause: Stable Diffusion model not downloaded

Solution:

# Models download automatically on first use
# Or manually download to:
resources/diffusion/models/

# Required files:
# - sd-v1-5-inpainting.ckpt
# - config.yaml

Getting More Help

If your issue isn't listed here:

  1. Check Logs
  2. Backend: logs/api.log
  3. Processing: process_log.txt

  4. Desktop: %APPDATA%/360-Hextile/logs/

  5. GPU Diagnostics bash nvidia-smi python -c "import cupy; print(cupy.cuda.runtime.getDeviceCount())"

  6. System Info bash python --version pip list | grep cupy nvidia-smi --query-gpu=name,driver_version --format=csv

  7. Search Documentation

  8. Use search bar (top of page)
  9. Check FAQ

  10. Review relevant guide

  11. Community Support

  12. GitHub Issues
  13. Discord community
  14. Stack Overflow

Preventive Measures

Before Processing

  • ✅ Check GPU temperature < 75°C
  • ✅ Close unnecessary applications
  • ✅ Verify sufficient disk space (10GB+)
  • ✅ Test with small template first

Regular Maintenance

  • Clear temp files weekly
  • Update GPU drivers monthly
  • Check for 360 Hextile updates
  • Monitor GPU health

Still having issues? Check GPU Setup or Performance Tips

Esc
Searching...
No results found.
Type to search the documentation
↑↓ Navigate ↵ Select Esc Close