How to Report Bugs in Open Notebook: A Step-by-Step Guide

To report a bug in Open Notebook, search existing issues first, then use the GitHub issue template at .github/ISSUE_TEMPLATE/bug_report.yml to document reproduction steps, expected vs. actual behavior, and your environment details.

Open Notebook follows an issue-first workflow to keep development focused and avoid duplicated effort. When you encounter unexpected behavior in the lfnovo/open-notebook repository, structured bug reporting ensures maintainers have the context needed to reproduce and fix issues quickly. This guide covers the official process defined in the project's contributing guidelines and issue templates.

The Issue-First Workflow

Before writing any code or opening a new ticket, Open Notebook requires contributors to verify the bug hasn't already been tracked.

Search Existing Issues First

According to the contributing guidelines in docs/7-DEVELOPMENT/contributing.md (lines 30-31), your first step is to search the repository's issue list for similar reports. This prevents duplicate issues and helps you find potential workarounds while waiting for an official fix. The guidelines explicitly mandate this search requirement to keep the backlog manageable.

When to Open a New Bug Report

If your search returns no relevant results, proceed to create a new issue using the official Bug Report template. This YAML template, located at .github/ISSUE_TEMPLATE/bug_report.yml (lines 1-6), enforces a consistent structure that maintainers need for efficient triage.

Using the Official Bug Report Template

The canonical template includes required fields that auto-format your submission into an actionable report.

Required Fields in the Template

The template mandates specific sections to eliminate ambiguity:

• What did you do when it broke? – Provide numbered steps to reproduce the bug (lines 13-18 in bug_report.yml)
• How did it break? – Clearly distinguish between expected and actual behavior (lines 26-33)
• Version & environment – Select your Open Notebook version and describe your OS, Docker setup, browser, etc. (lines 54-71)

Optional But Valuable Context

While not strictly required, these fields accelerate resolution:

• Logs or screenshots – Paste error traces or upload images (lines 38-45)
• Contribution checkbox – Check "I would like to work on this" if you plan to submit a fix (lines 87-94). This signals to maintainers that they should prioritize review and assignment for community-driven fixes.

Special Cases and Security Disclosures

Not all bugs should be reported publicly.

Reporting Security Vulnerabilities Privately

For security-related bugs, use GitHub Security Advisories instead of public issues. As documented in docs/7-DEVELOPMENT/security.md (lines 9-10), this private disclosure channel protects users from zero-day exploits while maintainers develop patches.

Automating Bug Reports with GitHub CLI

You can programmatically create bug reports using the GitHub CLI to ensure consistent formatting:

# Install the GitHub CLI first (https://cli.github.com/)

gh issue create \
  --repo lfnovo/open-notebook \
  --title "[Bug] Unexpected error when creating notebook" \
  --label "bug" --label "needs-triage" \
  --body "$(cat <<'EOF'

## What did you do when it broke?

1. Open the Notebooks page
2. Click "Create New Notebook"
3. Fill in the form and click "Save"

## How did it break?

**Expected:** Notebook is created and appears in the list.  
**Actual:** Received error "Failed to create notebook".

## Logs or Screenshots

docker compose logs -f open_notebook | tail -n 20

## Open Notebook Version

- Latest from main branch

## Environment

- OS: Ubuntu 22.04
- Docker: 24.0.5
- Browser: Chrome 120

## Additional Context

The issue started after upgrading to v1.5.0.

## Contribution

- [ ] I would like to work on this bug
EOF
)"

This command generates an issue body matching the official template structure, ensuring your report includes all critical debugging information.

Summary

• Search first – Check existing issues in lfnovo/open-notebook to avoid duplicates, as mandated in docs/7-DEVELOPMENT/contributing.md.
• Use the template – File bugs via .github/ISSUE_TEMPLATE/bug_report.yml with specific reproduction steps and environment details.
• Signal intent – Check the contribution box if you plan to fix the bug yourself.
• Security first – Report vulnerabilities privately through GitHub Security Advisories per docs/7-DEVELOPMENT/security.md.

Frequently Asked Questions

Where do I find the bug report template in Open Notebook?

The official bug report template is located at .github/ISSUE_TEMPLATE/bug_report.yml in the repository root. When you click "New Issue" on GitHub, this template automatically loads and structures your submission with required fields for reproduction steps and environment details.

What information is required when reporting a bug?

You must provide three core elements: numbered steps describing what you did when it broke, a clear comparison between expected and actual behavior, and your version and environment details including OS, Docker version, and browser. The template at lines 13-71 enforces these fields to ensure maintainers can reproduce the issue.

How do I report a security vulnerability privately?

For security-sensitive bugs, avoid public issues. Instead, submit through GitHub Security Advisories as documented in docs/7-DEVELOPMENT/security.md (lines 9-10). This private channel allows maintainers to patch vulnerabilities before public disclosure, protecting the user base from potential exploitation.

Can I indicate that I want to fix the bug myself?

Yes. The bug report template includes a checkbox at lines 87-94 stating "I would like to work on this." Checking this box signals to maintainers that you are a developer planning to submit a fix, which helps them prioritize issue assignment and review for community-driven contributions.

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