Handbook

Report an Issue

Report bugs and unexpected behavior through GitHub Issues. A short report with clear reproduction steps gives the team the best chance of identifying and fixing the problem.

Huabu uses GitHub Issues as its public feedback channel. Never include API keys, access tokens, private documents, or other sensitive data in an issue.

Before reporting

  • Update Huabu to the latest available version and check whether the problem still occurs.
  • Search existing issues in the Huabu issue tracker using the error message or a few words that describe the symptom.

If an existing issue describes the same problem, add any new reproduction details, your Huabu version, and your operating system to that issue instead of opening a duplicate.

Describe the problem

Use a specific title that describes the visible symptom, such as “PDF node becomes blank after reopening a Space.” In the report, include the following information:

FieldWhat to include
What happenedA short description of the behavior you observed, including any error message.
What you expectedWhat you were trying to do and what you expected Huabu to do instead.
Steps to reproduceA numbered list of the shortest sequence that triggers the problem.
FrequencyWhether it happens every time, sometimes, or only once, and whether it also happens in a new Space.

For example:

text
What happened
The PDF node is blank after I close and reopen its Space.

Expected behavior
The first page preview should appear after the Space reloads.

Steps to reproduce
1. Open Huabu and create a new Space.
2. Drag a PDF into the Space.
3. Return to Home, then reopen the Space.
4. The PDF node is blank.

Frequency
Every time with this PDF; it also happens in a new Space.

System information

Include the Huabu version, operating system version, CPU architecture, and whether you use the desktop or web app. In the desktop app, choose Help → Troubleshooting → Copy System Information, then paste the result into the issue.

Screenshots and logs

Add a screenshot or short screen recording when the problem is visual or difficult to describe. For crashes, failed requests, or unexpected errors, choose Help → Troubleshooting → Open Server Log and attach only the relevant part of server.log.

Review every attachment before uploading it. Remove API keys, access tokens, private conversations, personal information, confidential documents, and file paths that reveal information you do not want to publish.

AI-related problems

If the problem involves an AI response or edit, also include the details below. Share only the minimum context needed to understand the problem.

  • Whether you used Chat, Agent mode, or an Agent node, and whether it was powered by Huabu Agent or an external agent.
  • The provider and model name, but never the API key.
  • Which nodes or materials were selected as context.
  • The relevant prompt, response, or proposed edit, if safe to share, and whether you applied any proposed changes.

Submit the issue

Once the report contains the problem, expected behavior, reproduction steps, and system information, create a new GitHub issue. You can add screenshots or logs by dragging them into the issue editor.

A minimal reproduction is more useful than a large attachment. Share a sample file or exported Space only when it is necessary, safe to publish, and stripped of private content.