# How to Report a Bug in Deer-Flow: Web UI vs. GitHub Issues
> Learn how to report a bug in Deer-Flow using the web UI or manually submitting to GitHub issues. Follow our guide for a smooth reporting process.
- Repository: [Bytedance Inc./deer-flow](https://github.com/bytedance/deer-flow)
- Tags: how-to-guide
- Published: 2026-03-08
---
**You can report a bug in deer-flow either by clicking the "Report Issue" menu item in the web interface, which opens the GitHub Issues page directly, or by submitting a new issue manually via GitHub using the bug template defined in the project's CONTRIBUTING.md.**
DeerFlow is ByteDance's open-source AI workflow engine, and effective bug reporting is essential for maintaining its reliability across the React frontend and Python backend. The project standardizes on GitHub Issues as the single source of truth for tracking bugs, providing two complementary pathways for users to file reports. Understanding both methods—and the triage workflow that follows—ensures your issue gets resolved efficiently.
## Reporting a Bug via the DeerFlow Web UI
The fastest way to report a bug is through the built-in workspace navigation menu, which provides one-click access to the repository's issue tracker.
### The Workspace Menu Integration
In the frontend application, the workspace dropdown contains a dedicated **Bug** icon that links directly to the GitHub Issues page. This component is implemented in [[`frontend/src/components/workspace/workspace-nav-menu.tsx`](https://github.com/bytedance/deer-flow/blob/main/frontend/src/components/workspace/workspace-nav-menu.tsx)](https://github.com/bytedance/deer-flow/blob/main/frontend/src/components/workspace/workspace-nav-menu.tsx#L23-L31):
```tsx
{t.workspace.reportIssue}
```
- Clicking **Report Issue** opens `https://github.com/bytedance/deer-flow/issues` in a new browser tab.
- The `BugIcon` component and internationalized label `t.workspace.reportIssue` provide consistent UI access across all user sessions.
- This method is ideal for users who encounter errors during workflow execution and want to quickly navigate to the issue tracker without manually typing the URL.
## Reporting a Bug Directly on GitHub
For detailed bug reports or when you do not have the web UI open, submitting directly via GitHub follows the canonical process defined in the repository's contribution guidelines.
### The CONTRIBUTING.md Guidelines
The official workflow resides in the **"Need Help?"** section of [[`CONTRIBUTING.md`](https://github.com/bytedance/deer-flow/blob/main/CONTRIBUTING.md)](https://github.com/bytedance/deer-flow/blob/main/CONTRIBUTING.md#need-help). Follow these steps:
1. **Search existing issues** – Check the open issues list to avoid duplicates before creating a new entry.
2. **Use the bug template** – Select the *Bug* template when creating a new issue to ensure sections for reproduction steps, expected behavior, and environment details are included.
3. **Provide clear context** – Include screenshots, error logs, steps to reproduce, and minimal code snippets that trigger the failure.
### Structuring Your Bug Report
A well-structured report accelerates triage. Here is the markdown format recommended by the DeerFlow maintainers:
```markdown
### Description
The "Upload files" button fails with a 500 error when uploading a PDF larger than 5 MB.
### Steps to Reproduce
1. Open the DeerFlow UI.
2. Click **Upload** → select a >5 MB PDF.
3. Observe the error toast.
### Expected Behavior
The file should be uploaded and appear in the thread's **Artifacts** panel.
### Environment
- DeerFlow version: `main` (commit `a1b2c3d`)
- Browser: Chrome 122.0
- Backend: Python 3.12, uv 0.2.10
- Sandbox mode: Docker
```
## The Triage and Resolution Workflow
Once submitted, your bug report enters a structured lifecycle managed by automated workflows and maintainers.
### Auto-Labeling and Assignment
New issues are automatically labeled with `bug` based on repository automation (see [`.github/workflows/backend-unit-tests.yml`](https://github.com/bytedance/deer-flow/blob/main/.github/workflows/backend-unit-tests.yml) for label management logic). Maintainers then triage the issue, assign it to a developer, and link related pull requests.
### Test-Driven Fixes
If the bug is reproducible, the assignee creates a regression test case in the extensive test suite under `backend/tests/` (e.g., [`test_uploads_router.py`](https://github.com/bytedance/deer-flow/blob/main/test_uploads_router.py) for upload-related bugs) before implementing the fix. This ensures the specific failure mode is permanently prevented in future releases.
## Programmatic Bug Reporting Examples
For developers building integrations or automated testing pipelines, you can programmatically open issues using the GitHub REST API.
### Opening the Report Link Programmatically
To replicate the UI behavior in a custom dashboard:
```tsx
import { BugIcon } from '@/components/icons';
import { t } from '@/i18n';
// Inside the workspace dropdown component
{t.workspace.reportIssue}
```
### Creating Issues via the GitHub API
For automated error reporting from deployment systems:
```bash
curl -X POST \
-H "Authorization: token $GITHUB_TOKEN" \
-H "Accept: application/vnd.github+json" \
https://api.github.com/repos/bytedance/deer-flow/issues \
-d '{
"title": "[BUG] Upload fails for large PDFs",
"body": "### Description\nThe upload endpoint returns 500 …\n\n### Steps to Reproduce\n1. …\n2. …\n\n### Environment\n- DeerFlow: main\n- …",
"labels": ["bug"]
}'
```
## Summary
- **Two entry points**: Use the **Report Issue** menu in [`frontend/src/components/workspace/workspace-nav-menu.tsx`](https://github.com/bytedance/deer-flow/blob/main/frontend/src/components/workspace/workspace-nav-menu.tsx) for quick access, or file directly via GitHub Issues using the template in [`CONTRIBUTING.md`](https://github.com/bytedance/deer-flow/blob/main/CONTRIBUTING.md).
- **Structured reports matter**: Include reproduction steps, expected behavior, and environment details to match the project's standards.
- **Automated triage**: Issues receive the `bug` label automatically and are tracked through resolution with tests added to `backend/tests/`.
- **Single source of truth**: All bugs, whether reported via UI or GitHub, converge in the GitHub Issues tracker for the ByteDance/deer-flow repository.
## Frequently Asked Questions
### Can I report a bug in deer-flow without a GitHub account?
No, DeerFlow requires a GitHub account to submit bug reports because the project uses GitHub Issues as its exclusive issue-tracking system. The web UI merely provides a convenient hyperlink to the repository's Issues page, where you must authenticate to create a new entry.
### What information should I include when reporting a bug?
According to the [`CONTRIBUTING.md`](https://github.com/bytedance/deer-flow/blob/main/CONTRIBUTING.md) guidelines, you should include a clear description, numbered steps to reproduce, expected versus actual behavior, and environment details such as DeerFlow version (commit hash), browser version, Python version, and sandbox mode (Docker or local). Screenshots and error logs significantly improve resolution time.
### How long does it take for a bug report to be triaged?
While timelines vary based on severity and maintainer availability, the automated workflow in [`.github/workflows/backend-unit-tests.yml`](https://github.com/bytedance/deer-flow/blob/main/.github/workflows/backend-unit-tests.yml) immediately applies the `bug` label upon submission. Critical issues affecting core workflow functionality typically receive maintainer assignment within 24-48 hours, while enhancement requests may take longer.
### Where are regression tests for bugs stored?
After a bug is confirmed and fixed, developers add regression tests to the `backend/tests/` directory (for example, [`test_uploads_router.py`](https://github.com/bytedance/deer-flow/blob/main/test_uploads_router.py) for upload-related bugs). These tests verify that the specific failure mode cannot recur in future releases of the Python backend.