How to Report a Bug in Deer-Flow: Web UI vs. GitHub Issues

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#L23-L31):

<a
  href="https://github.com/bytedance/deer-flow/issues"
  target="_blank"
  rel="noopener noreferrer"
>
  <DropdownMenuItem>
    <BugIcon />
    {t.workspace.reportIssue}
  </DropdownMenuItem>
</a>

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

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

import { BugIcon } from '@/components/icons';
import { t } from '@/i18n';

// Inside the workspace dropdown component
<a
  href="https://github.com/bytedance/deer-flow/issues"
  target="_blank"
  rel="noopener noreferrer"
>
  <DropdownMenuItem>
    <BugIcon />
    {t.workspace.reportIssue}
  </DropdownMenuItem>
</a>

Creating Issues via the GitHub API

For automated error reporting from deployment systems:

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 for quick access, or file directly via GitHub Issues using the template in 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 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 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 for upload-related bugs). These tests verify that the specific failure mode cannot recur in future releases of the Python backend.

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