microsoft--magentic-ui
wehub-resource-sync
25576b0be6
Checks (magui2.0) / python-lint (push) Failing after 1s
Checks (magui2.0) / python-test (push) Failing after 0s
Checks (magui2.0) / frontend-lint (push) Failing after 0s
CodeQL Advanced / Analyze (actions) (push) Failing after 1s
Checks (magui2.0) / python-format (push) Failing after 1s
CodeQL Advanced / Analyze (python) (push) Failing after 0s
Checks (magui2.0) / python-pyright (push) Failing after 1s
Checks (magui2.0) / frontend-format (push) Failing after 1s
Checks (magui2.0) / frontend-typecheck (push) Failing after 0s
Checks (magui2.0) / frontend-test (push) Failing after 2s
CodeQL Advanced / Analyze (javascript-typescript) (push) Failing after 1s
88 行
4.2 KiB
Markdown
88 行
4.2 KiB
Markdown
# Troubleshooting
|
|
|
|
## Model endpoint cold starts
|
|
|
|
If you're using a managed model endpoint that scales to zero when idle (Hugging Face Inference Endpoints with scale-to-zero, for example), the **first call after the endpoint has been idle** may take **30–90 seconds** while the platform brings a replica back up. During that window you may see:
|
|
|
|
- a `503` response or a `Verify & Save` error in MagenticLite's Settings, or
|
|
- the first chat turn appearing to hang.
|
|
|
|
Wait a minute and try again. Subsequent requests respond at normal speed until the endpoint scales to zero again.
|
|
|
|
See the [Model Hosting Guide](./model-hosting-guide.md#a3-scale-to-zero-and-cold-starts) for the full explanation.
|
|
|
|
## Settings → Models verification fails
|
|
|
|
When you click **Verify & Save**, MagenticLite sends a probe request to the endpoint. Common failures:
|
|
|
|
| Symptom (banner) | Likely cause |
|
|
| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
|
|
| `Endpoint returned HTTP 401` or `403` | API Key field is empty or wrong (different endpoints return one or the other for the same problem) |
|
|
| `Endpoint returned HTTP 503` on the first attempt | Cold start — see the section above; wait a minute and click Verify again |
|
|
| `Connection refused — is the server running?` or other network errors | Endpoint URL is wrong (typo in the host, missing `https://`, VPN/firewall issue) |
|
|
|
|
Re-check the values against the source you copied them from (the Hugging Face dashboard, the Foundry deployment page, etc.) and try again.
|
|
|
|
## Installation and runtime
|
|
|
|
### `magentic-ui` command not found
|
|
|
|
Your virtual environment isn't activated. Re-activate it and try again:
|
|
|
|
```bash
|
|
deactivate # if another env is active
|
|
source .venv/bin/activate
|
|
magentic-ui --port 8081
|
|
```
|
|
|
|
### Port 8081 already in use
|
|
|
|
Another MagenticLite process is already running on the same port. Stop it, or run on a different port:
|
|
|
|
```bash
|
|
magentic-ui --port 8082
|
|
```
|
|
|
|
### Quicksand VM fails to start (Linux/WSL2)
|
|
|
|
- Confirm KVM is available: `[ -e /dev/kvm ] && echo ok` should print `ok`.
|
|
- Confirm your user is in the `kvm` group: `groups | grep -q kvm && echo ok`. If not, run `sudo usermod -aG kvm $USER` and restart your shell.
|
|
- Without KVM the VM falls back to software emulation, which is significantly slower but should still work.
|
|
|
|
### Browser viewer is blank or unresponsive
|
|
|
|
- Make sure the Quicksand VM is healthy (check the MagenticLite logs for `quicksand` errors).
|
|
- Check that any local firewall isn't blocking the noVNC port the app picks for the embedded browser viewer.
|
|
- Restart MagenticLite — the browser is recreated on each session.
|
|
|
|
## Coming from Magentic-UI 0.1.x?
|
|
|
|
The 0.1.x line of Magentic-UI is still on PyPI under the same `magentic_ui` package name, and its on-disk data lives in the same default app directory. A few things to be aware of:
|
|
|
|
### `pip install` picks up Magentic-UI 0.1.x instead of MagenticLite
|
|
|
|
A plain `uv pip install magentic_ui` (no version pin) may resolve to a 0.1.x release. Pin to a 0.2.x version explicitly:
|
|
|
|
```bash
|
|
uv pip install "magentic_ui>=0.2.0"
|
|
```
|
|
|
|
(Adjust the version to whatever 0.2.x release you intend to run.)
|
|
|
|
### MagenticLite reads / writes my old Magentic-UI 0.1.x data
|
|
|
|
MagenticLite (0.2.x) doesn't migrate the 0.1.x database. By default both versions use the same app directory, which can lead to confusing state. To keep them separate, point MagenticLite at a different `--appdir`:
|
|
|
|
```bash
|
|
magentic-ui --port 8081 --appdir ~/.magentic-lite
|
|
```
|
|
|
|
## Still having issues?
|
|
|
|
- Re-check the [Installation Guide](./installation.md) and [Configuration](./configuration.md).
|
|
- Search [GitHub Issues](https://github.com/microsoft/magentic-ui/issues) for similar problems.
|
|
- Open a new issue and include:
|
|
1. A detailed description of your problem
|
|
2. Information about your system (OS, hardware acceleration support, MagenticLite version)
|
|
3. Steps to reproduce the issue
|