# Troubleshooting

Common issues and how to fix them.

## Runtime issues

### `./run.sh` fails with `pydantic_core not valid for use in process`

macOS blocked the Python library. Fix:
```bash
xattr -dr com.apple.quarantine .venv
# or
rm -rf .venv && ./run.sh  # re-creates venv
```

### Workflow stuck on "Queueing" forever

- The GPU runner is booting up (~5 min first time). Check the runner dashboard.
- If it's been >5 min, check the runner logs for setup errors.
- Try refreshing the page.

### "Unprocessable Entity" (422) error

The runner isn't ready yet — the proxy now auto-retries on 422 up to 5 times. If it still fails:
- Wait 30 seconds and retry.
- Check the runner is "Active" on the dashboard.

### Workflow crashes mid-execution

- Check the **runner logs** on the dashboard — the error is usually clear.
- Common causes:
  - **OOM (out of memory)**: your models + input sizes exceed 80GB VRAM. Reduce batch/resolution or use fp8 variants.
  - **Model not found**: model referenced isn't available. See [ADD_MODELS.md](ADD_MODELS.md).
  - **Size mismatch**: model architecture incompatible with ComfyUI version.

### Video preview doesn't update when I change frame count

The VHS Advanced Preview uses local ffmpeg. Check:
- `ffmpeg` is installed: `which ffmpeg`
- The video file is in `userdata/file_storage.json`
- Re-upload the video if it was from a previous session

### Outputs page shows too many files / previews

Fixed — the proxy now filters only `type == "output"` files.
PreviewImage and VHS temp files are excluded automatically.

### "2 jobs running" when only 1 was queued

Fixed — queue tracking is now synchronized.

## Models & Nodes

### Red border around a node

A model referenced by the node isn't in the server's list.
- Check `http://localhost:8188/api/experiment/models/<folder>` to see what's available.
- Change the node's model dropdown to an existing one, or [add the missing model](ADD_MODELS.md).

### Node shows as "UNKNOWN"

The custom node crashed on import.
- Check the runner startup logs for `ImportError` or similar.
- Usually a missing Python package — add it to `requirements.txt` and redeploy.

### LTX 2.3 "scale_shift_table size mismatch"

ComfyUI is too old — update `COMFY_COMMIT_HASH` to v0.19.0 or later.

## Deployment

### `make deploy` fails with dependency conflict

```
× No solution found when resolving dependencies
```

Some Python packages conflict. Usually fixed by:
- Relaxing a pin (`==` → `>=`)
- Or removing conflicting packages

### Runner stuck on "SETUP" for 10+ minutes

The setup is timing out. Possible causes:
- Huge model downloads on first start (expected, up to 30 min)
- Network issue downloading a model
- A custom node's `git clone` is hanging

Kill the runner and retry.

### Runner crashes with `ModuleNotFoundError`

A custom node's Python dependency is missing.
- Find the missing module name in the error.
- Add it to `requirements.txt`.
- `make deploy` and kill the runner.

## Windows-specific

### "Set-ExecutionPolicy" error running `.\run.ps1`

Allow local scripts:
```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

### `winget` not found

Install App Installer from Microsoft Store:
https://apps.microsoft.com/detail/9NBLGGH4NNS1

### uv / ffmpeg not in PATH after winget install

Close and reopen the terminal — PATH is refreshed.

## Proxy / Frontend

### Proxy shows old node definitions

Clear the cache:
```bash
rm node_class_mappings.*.json
./run.sh
```

### Can't upload large files (>500MB)

Edit `proxy/fal_comfy_server.py`, find `MAX_FILE_SIZE` and increase it.

### Videos don't play in /outputs page

The proxy downloads the video through `/api/download`. If it fails:
- Check the fal.media URL is still valid (7-day TTL)
- Check network connection

## Getting help

1. **Logs first**: runner logs usually tell you exactly what's wrong.
2. **Check the right runner**: the `./run.sh` output gives you a direct link to YOUR runner.
3. **Reproduce with a minimal workflow**: simpler workflows = easier debugging.
4. **Ask Lovis** with:
   - The runner ID
   - Screenshot of the error in the UI
   - Relevant logs (last 50 lines)
