# How to Report a Bug in Jellium-Desktop: A Complete Guide to Logs and Templates

> Learn how to report a bug in Jellium-Desktop. Follow our guide to use the bug report template, provide necessary logs, and ensure faster fixes for Jellium-Desktop.

- Repository: [Andrew Rabert/jellium-desktop](https://github.com/andrewrabert/jellium-desktop)
- Tags: how-to-guide
- Published: 2026-07-20

---

**To report a bug in jellium-desktop, open a GitHub issue using the template at [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/andrewrabert/jellium-desktop/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml), fill in your platform and version details, and attach the `build/run.log` file produced by running `just run`.**

Jellium-Desktop is a Rust-based desktop client that embeds the Jellyfin web UI with **CEF** and delegates all video playback to **mpv**. Because playback state is driven by mpv and propagated to the UI via IPC, maintainers need exact environment details and debug logs to trace issues across the Rust host, CEF subprocess, and video layer. Providing the information requested in the official bug report template is the fastest way to get a reproducible issue triaged.

## Use the Official Bug Report Template

The repository provides a structured GitHub issue template at [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/andrewrabert/jellium-desktop/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml). You should fill out every field completely. Incomplete submissions often lack the context required to reproduce bugs in platform-specific code paths such as those found in `src/macos` and `src/windows`.

### Provide Exact Version and Platform Information

Include the exact **Version** string shown in the app’s **About** dialog, for example `0.1.0-dev+fffffff`. For **Platform**, select *Linux / Wayland*, *Linux / X11*, *macOS*, or *Windows*, and supply your operating-system version. Your **GPU** model also matters because video-layer handling branches by driver and display server, including Wayland subsurfaces versus X11 windows.

### Describe the Bug and Reproduction Steps

In **Describe the bug**, summarize the observed behavior in plain language. In **Steps to reproduce**, provide a numbered list of actions that trigger the issue reliably. Precise steps are essential because the UI layer in `src/jfn_cef/*` never decides playback state itself; instead it reflects mpv state propagated via IPC, so interactions can be timing-sensitive.

### Confirm the Custom UI Disclosure

The first checkbox in the template requires you to confirm whether you are using custom styles or plugins that modify the web UI. Accepting this ensures developers know they are debugging the unmodified Jellyfin interface rather than third-party modifications.

## Collect and Attach Debug Logs

Logs are the most critical artifact for diagnosing issues in this multi-process application. Jellium-Desktop’s logging backend in [`src/logging/src/lib.rs`](https://github.com/andrewrabert/jellium-desktop/blob/main/src/logging/src/lib.rs) writes simultaneously to **stderr** and a rotating file, while the redaction module in [`src/logging/src/redact.rs`](https://github.com/andrewrabert/jellium-desktop/blob/main/src/logging/src/redact.rs) automatically strips authentication tokens. This gives maintainers visibility into events from the CEF glue code in `src/jfn_cef/*` and the mpv layer in `third_party/mpv/*`.

To generate a log, run the application with debug output enabled:

```bash
just run

```

After reproducing the bug, locate `build/run.log` in your project root and attach it to the issue. If you have overridden the default path with the `JELIUM_LOG_PATH` environment variable, use that path instead.

### Rotating File Limits

The rotating logger keeps files manageable by enforcing these limits, as defined in [`src/logging/src/lib.rs`](https://github.com/andrewrabert/jellium-desktop/blob/main/src/logging/src/lib.rs):

```rust
const MAX_FILE_BYTES: u64 = 10 * 1024 * 1024;
const MAX_BACKUPS: usize = 3;

```

### Initialize Logging Programmatically

The `init` function in [`src/logging/src/lib.rs`](https://github.com/andrewrabert/jellium-desktop/blob/main/src/logging/src/lib.rs) accepts an optional file path. When a non-empty path is supplied, the logger creates a `RotatingFile` writer limited to 10 MiB with three backups. If you embed the binary programmatically, you can initialize logging manually:

```rust
use jellium_desktop::logging::init;
use std::path::PathBuf;

fn main() {
    // Initialise logging, directing file output to "jellium.log"
    init(PathBuf::from("jellium.log"));
    // … normal startup …
}

```

All output is filtered for sensitive values before it is written, so the attached log is safe to share publicly.

## Summary

- Use the template at [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/andrewrabert/jellium-desktop/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml) whenever you report a bug in jellium-desktop.
- Include exact version, platform, OS version, and GPU to identify relevant code paths in `src/macos`, `src/windows`, and display-server logic.
- Always attach the `build/run.log` generated by `just run` so maintainers can correlate Rust/CEF events with mpv state.
- Disclose any custom styles or plugins that modify the Jellyfin web UI via the template’s required checkbox.

## Frequently Asked Questions

### Where is the bug report template located?

The official template lives at [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/andrewrabert/jellium-desktop/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml) in the repository root. When you click **New issue** on GitHub, this form is rendered automatically.

### What log file should I attach to a bug report?

Attach `build/run.log`, which is produced when you launch the application with `just run`. The path can be changed via the `JELIUM_LOG_PATH` environment variable if you have customized it.

### How does Jellium-Desktop protect sensitive data in logs?

The redaction logic in [`src/logging/src/redact.rs`](https://github.com/andrewrabert/jellium-desktop/blob/main/src/logging/src/redact.rs) filters authentication tokens and other secrets before they reach the log writers in [`src/logging/src/lib.rs`](https://github.com/andrewrabert/jellium-desktop/blob/main/src/logging/src/lib.rs), ensuring that captured output is safe to post publicly.

### Do I need to disclose custom Jellyfin plugins or themes?

Yes. The first checkbox in the bug report template requires you to confirm that you will disclose any custom styles or plugins that modify the web UI. This prevents maintainers from chasing bugs caused by third-party modifications.