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

To report a bug in jellium-desktop, open a GitHub issue using the template at .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. 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 writes simultaneously to stderr and a rotating file, while the redaction module in 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:

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:

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 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:

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 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 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 filters authentication tokens and other secrets before they reach the log writers in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}