Troubleshooting
Start with the symptom. Check the boundary. Take one concrete action.
Collect the basics
shell
docker compose ps
docker compose logs --tail=100 lumina
curl -fsS http://127.0.0.1:8765/api/healthUse Manage Server → Maintenance → Diagnostics for server details. Remove credentials, private paths, and media details before sharing logs.
Find the next action
| Symptom | Check | Action |
|---|---|---|
| Cannot open the app remotely | Default port is loopback-only. | Configure HTTPS; verify proxy origin and immediate peer. |
| Container exits at startup | Logs name invalid environment, permissions, or schema. | Correct the named setting. Match UID/GID to the data owner. Never reset the database to hide an error. |
| Folder not available | Host mount, container path, allowed mount parent. | Mount under /media, register the container path, import once. |
| Root is offline / identity mismatch | Actual mounted filesystem or share. | Restore the expected mount. Do not replace it with an empty directory. |
| Imported title is wrong | NFO fields, filename, selected metadata match. | Use Unmatched → Fix match or edit the title. |
| Video pauses during conversion | GPU availability, CPU load, playback tmpfs. | Inspect playback diagnostics; use direct play or lower quality, or increase available resources. |
| An arr request is not playable | Path mapping, enabled root, first import, visible local file. | Fix mapping and import. An upstream download alone is insufficient. |
| Jellyfin client rejects sign-in | API enabled, correct public address, two-step verification. | Use a per-device app password. Review the supported API subset. |
| AI action is missing | Feature enabled and required endpoint/model available. | Test assistant/speech setup or use the documented no-AI workflow. |
| YouTube / Twitch refuses playback | Provider restriction, expired session, protected stream. | Reconnect an optional personal session or use the provider’s own player. DRM is unsupported. |
Report a reproducible issue
Include the Lumina version, host architecture, browser or client, exact steps, expected result, and sanitized diagnostics. Open an issue. Report vulnerabilities through the security policy.
Applies to Lumina 0.4.0. Source: operator guide