Skip to main content

Reporting Bugs

Reporting bugs effectively helps the Radix IoT team identify and fix issues quickly. A well-written bug report with the right diagnostic information can mean the difference between a fix in days versus weeks of back-and-forth. This guide explains what to check before reporting, what information to include, and where to submit your report.

Before Asking for Help​

Before submitting a bug report, rule out common issues and check existing resources:

  1. Check the Troubleshooting section on the documentation site. The issue may already be documented with a known fix or workaround.
  2. Search the Mango community forum. Look in the Mango Feedback category to see if other users have reported the same issue.
  3. Check the release notes for your Mango version. The issue may have been addressed in a newer release.
  4. Try to reproduce the issue in a clean environment if possible. This helps determine whether the issue is caused by your specific configuration or is a general bug.

What Makes a Good Bug Report​

A good bug report allows the development team to reproduce the issue. Include the following:

Isolation Steps​

Try to isolate the problem to its smallest reproducible case:

  • Disable other data sources or data points to determine if the issue is related to a specific configuration.
  • If the issue is with a custom page, extract the minimal markup that reproduces the problem.
  • If the issue is intermittent, note any patterns (time of day, specific user actions, system load conditions).

Reproduction Steps​

Describe in detail the exact steps to reproduce the issue:

  1. What page or feature were you using?
  2. What actions did you take, in what order?
  3. What happened (the actual result)?
  4. What did you expect to happen (the expected result)?

Required Information​

Every bug report must include:

  • Mango version: The exact version number (e.g., 4.5.1).
  • Relevant module versions: If the issue involves a specific module (e.g., Modbus, BACnet, mangoUI), include that module's version number.
  • Log file entries: Check <MA_HOME>/logs/ma.log for errors or warnings near the time the issue occurred. Include the relevant log entries in your report. The support team may request the full log file.
  • Operating system: The OS running on the Mango server (e.g., Ubuntu 22.04, Windows Server 2019, macOS). If using a MangoES appliance, note this specifically.

For UI Issues​

In addition to the required information above, UI bug reports must include:

  • mangoUI module version.
  • Browser errors: Errors from the browser developer console (see instructions below).
  • Browser version: The specific browser and version you are using (e.g., Chrome 120, Firefox 121). Use the latest Chrome or Firefox for best compatibility. Safari and Edge are also supported. Internet Explorer is not supported.
  • Screenshots: Screenshots or screen recordings of the issue help clarify what is happening.

For Custom Page Issues​

If the issue is with a custom dashboard or page:

  • Include the isolated markup that reproduces the issue.
  • The support team may ask for the full page markup.

Capturing Browser Error Messages​

Using Chrome:

  1. Open the developer tools by pressing Ctrl+Shift+J (Windows/Linux) or Cmd+Opt+J (macOS).
  2. Switch to the Console tab.
  3. Refresh the page (F5 or Ctrl+R).
  4. Perform the action on the page that causes your issue.
  5. Copy the error messages. You can right-click in the console and select "Save as" to save the entire console log to a file.

For more information on using Chrome developer tools, see the Chrome DevTools documentation.

Where to Report Bugs​

Bug Report Template​

When filing a GitHub issue or forum post, use this template:

**Mango Version**: [e.g., 4.5.1]
**Module Versions**: [relevant module versions]
**Operating System**: [e.g., Ubuntu 22.04]
**Browser**: [e.g., Chrome 120] (for UI issues)

**Description**:
[Brief description of the issue]

**Steps to Reproduce**:
1. [First step]
2. [Second step]
3. [Third step]

**Expected Result**:
[What should happen]

**Actual Result**:
[What actually happens]

**Log Entries**:
[Relevant entries from ma.log]

**Browser Console Errors**:
[Errors from the browser console, if applicable]

**Screenshots**:
[Attach screenshots if helpful]

Following this template ensures the development team has all the information needed to investigate and resolve the issue efficiently.