How to Report a Bug or Crash in FreeCAD

Reporting a bug or crash to the FreeCAD development team ensures that software defects are tracked and resolved efficiently. This guide outlines the essential steps to prepare, document, and submit an issue, including gathering system information, discussing the problem on the community forum, and filing a formal report on GitHub with actionable reproduction steps.

1. Test with the Latest Release

Before submitting a report, verify whether the issue has already been fixed. Download and test the latest stable release or the development weekly build. If the problem does not occur in newer versions, a report is no longer necessary.

2. Copy Your System Information

FreeCAD includes a built-in tool to capture your exact platform details, which developers need to reproduce issues.

  1. Open FreeCAD.
  2. Navigate to Help > About FreeCAD.
  3. Click the Copy to clipboard button.
  4. Save this text, as you will need to paste it directly into your report.

3. Check for Existing Reports

Check if someone else has already reported the issue:

  • Search the FreeCAD GitHub Issues tracker.
  • Search the FreeCAD Forum. If an existing report matches your problem, add your system details and observations to that thread rather than creating a duplicate.

4. Discuss the Issue on the Forum First

The FreeCAD project policy asks users to discuss potential bugs on the forum before creating a GitHub issue.

  1. Go to the FreeCAD Forum and choose an appropriate section, such as Help on using FreeCAD or Open Discussion.
  2. Create a topic describing what happened, what you expected to happen, and include the system information copied from step 2.
  3. Community members and developers will help determine whether the issue is a software bug, a workflow mistake, or a platform-specific quirk.

5. Submit an Issue on GitHub

If forum contributors confirm the behavior is a bug, or if you are dealing with a reproducible crash, file a ticket on the FreeCAD GitHub repository:

  1. Go to the official FreeCAD repository on GitHub and navigate to the Issues tab.
  2. Click New Issue.
  3. Choose the appropriate template (Bug Report or Crash Report).
  4. Fill out all requested fields:
    • Title: A concise, descriptive summary of the problem.
    • FreeCAD Info: Paste your system information copied from the "About FreeCAD" dialog.
    • Steps to Reproduce: Provide clear, numbered steps starting from a blank document.
    • Attachments: Attach sample .FCStd files, screenshots, or screen recordings that illustrate the failure.

6. Providing Crash Logs and Backtraces (For Crashes Only)

If FreeCAD closes unexpectedly, a backtrace provides the exact line of code that triggered the failure:

  • Linux: Run FreeCAD inside gdb (gdb freecad), trigger the crash, and run the command bt to capture the backtrace.
  • Windows: When prompted by an unhandled exception or crash handler, copy the detailed crash log, or use the console version (FreeCADCmd.exe) to observe terminal output.
  • Attach the generated backtrace or log file to your GitHub issue to help developers pinpoint the root cause immediately.