How to Report a Bug in Onyx: The Complete Contributor Guide

To report a bug in Onyx, file a structured GitHub Issue in the onyx-dot-app/onyx repository with environment details, reproduction steps, and the bug label, following the workflow defined in CONTRIBUTING.md.

The onyx-dot-app/onyx repository maintains a well-defined contribution infrastructure that streamlines how users report bugs. Whether you are running Onyx via Docker, Helm, or local development, submitting a clear and reproducible bug report helps the core team triage and resolve issues efficiently. The process is deliberately simple so contributors can provide actionable information that maintainers can diagnose quickly.

File a GitHub Issue

According to the Onyx source code, all bug reports must be filed as issues in the GitHub repository. The official guidance resides in CONTRIBUTING.md at lines 5-9, which directs contributors to use the Issues tab for bug tracking.

When creating a new issue, select the Bug template if available, or manually apply the bug label to ensure proper categorization. If you encounter a critical security or functionality failure, you can @-mention a maintainer such as @yuhongsun96 in the issue comments to expedite attention.

Structure a Complete Bug Report

A high-quality bug report contains specific sections that allow maintainers to reproduce and diagnose the problem quickly.

Environment Specifications

Include your exact deployment context to eliminate configuration guesswork:

• Onyx version: Run git rev-parse HEAD to capture the commit hash
• Deployment mode: Docker, Helm, or local development environment
• Operating system and browser version (for UI-related issues)

Reproduction Steps and Expected Behavior

Document the exact sequence of actions that triggers the failure. Include CLI commands (onyx commands) or specific UI interactions. Clearly distinguish between observed behavior (error messages, stack traces, UI crashes) and expected behavior (what should have happened).

Attach Logs and Screenshots

Provide backend logs from backend/log/<service>_debug.log or frontend console output to illustrate the failure. For UI bugs originating in web/src/app/* components, attach screenshots or screen recordings showing the error state.

Triage and Labeling

If you have write permissions, apply standardized labels to accelerate triage:

• bug: Signals the issue type
• severity:high, severity:medium, or severity:low: Indicates business impact
• component:frontend, component:backend, component:connector, or component:celery: Points to the affected subsystem

The contribution process documented in contributing_guides/contribution_process.md at lines 3-6 explains how the core team verifies and prioritizes labeled issues. Always search existing issues before filing to avoid duplicates. If your bug report leads to a fix, reference .github/pull_request_template.md when submitting the subsequent PR.

Automation and Code Examples

Streamline your reporting workflow using command-line tools and reproducible scripts.

Using GitHub CLI

The following command creates a properly labeled issue with structured markdown content:

gh issue create \
  --title "Chat UI crashes when uploading a PDF" \
  --label bug,component:frontend \
  --body "## Environment

- Onyx version: $(git rev-parse HEAD)
- OS: macOS 14.2
- Browser: Chrome 124

## Steps to Reproduce

1. Open the chat UI at http://localhost:3000.
2. Click the attachment button and select a PDF > 5 MB.
3. Observe the crash.

## Expected

File uploads should display a progress bar and succeed.

## Actual

The UI throws a JavaScript error and the page reloads.

## Logs

\`\`\`bash
docker logs onyx-web_1 2>&1 | grep \"upload\"
\`\`\`
"

Minimal Reproduction Script

For backend API bugs, provide a Python snippet that isolates the failure:

import requests

url = "http://localhost:3000/api/chat/file/upload"
files = {"file": ("sample.pdf", open("sample.pdf", "rb"), "application/pdf")}

resp = requests.post(url, files=files)
print(resp.status_code, resp.text)   # Expected 200, got 500 – reproduces #bug

Summary

• File all bug reports as GitHub Issues in the onyx-dot-app/onyx repository per CONTRIBUTING.md lines 5-9
• Structure reports with environment specs, reproduction steps, and observed vs. expected behavior
• Attach logs from backend/log/<service>_debug.log and reference web/src/app/* for UI issues
• Apply labels including bug, severity:*, and component:* to aid triage per contributing_guides/contribution_process.md
• Use the GitHub CLI or Python scripts to create reproducible examples that speed up resolution

Frequently Asked Questions

Where do I find the official bug reporting guidelines?

The primary source for contribution rules resides in CONTRIBUTING.md at the repository root, specifically lines 5-9. This file defines the GitHub Issues workflow and links to contributing_guides/contribution_process.md for triage details.

What information is required for a bug report to be actionable?

You must provide the Onyx version (commit hash), deployment method (Docker/Helm/local), exact reproduction steps, observed error messages or stack traces, and relevant logs from backend/log/<service>_debug.log. Screenshots are required for UI bugs affecting components in web/src/app/*.

Can I report a bug if I don't know which component is affected?

Yes. Apply the general bug label when creating the issue. Maintainers will triage the report and add the appropriate component:* label (frontend, backend, connector, or celery) during review according to the process in contributing_guides/contribution_process.md.

How do I report critical bugs that need immediate attention?

For critical failures, create the GitHub Issue with the severity:high label and @-mention a core maintainer like @yuhongsun96 in the issue description. Include "CRITICAL" in the title prefix and attach complete logs to facilitate emergency triage.

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