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

> Report a bug in Onyx by filing a structured GitHub Issue in the onyx-dot-app/onyx repository. Follow the contributing guide for reproduction steps and environment details.

- Repository: [Onyx/onyx](https://github.com/onyx-dot-app/onyx)
- Tags: how-to-guide
- Published: 2026-03-28

---

**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`](https://github.com/onyx-dot-app/onyx/blob/main/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`](https://github.com/onyx-dot-app/onyx/blob/main/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`](https://github.com/onyx-dot-app/onyx/blob/main/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`](https://github.com/onyx-dot-app/onyx/blob/main/.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:

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

```python
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`](https://github.com/onyx-dot-app/onyx/blob/main/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`](https://github.com/onyx-dot-app/onyx/blob/main/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`](https://github.com/onyx-dot-app/onyx/blob/main/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`](https://github.com/onyx-dot-app/onyx/blob/main/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`](https://github.com/onyx-dot-app/onyx/blob/main/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.