Reporting Issues with pfSense Software

This page serves as a guide for providing legitimate bug reports with pfSense® software. Most of the bug reports Netgate receives from users are not bugs, but incorrect configurations. Often user reports do not contain nearly enough information for a developer to replicate the problem. If a bug report does not contain the appropriate information to verify a legitimate bug, developers have no choice but to reject the report.

Attention

The pfSense Redmine site is not a discussion platform and is never to be used for assistance requests.

The first step is typically to ask about the problem using one of the available resources for assistance, such as the Netgate Forum. An issue report can be opened if a specific bug is found that can be reproduced by developers.

An example of an invalid bug report is XYZ doesn't work! without appropriate accompanying detail. An alternative, to make that a legitimate bug report, is:

Subject:
  Feature XYZ generates an invalid configuration for option A on
  ``thispage.php``

Description:
  The underlying @xyz.conf@ has @option1=1@ where it should be @option1=5@
  when option A is checked on @thispage.php@ in the web interface.

See also

How to report bugs effectively.

What to Avoid

Do not submit reports generated by Large Language Model (LLM, “AI”) or similar systems. Nearly all of these reports contain incorrect, invalid, or irrelevant information. They also frequently include items that do not exist or make claims that have not been tested or verified. Many of these reports also include formatting and phrasing that makes them inefficient and over-complicated. The original prompt fed to these systems is typically a better report than what they generate.

Reports made using these types of automated systems will be rejected.

Users who are not familiar with reporting issues should instead post to the Netgate Forum and discuss the problem first. Other forum users can assist with diagnosing and reporting the issue as needed.

Where to submit

For anything that is not a confirmed, specific, detailed bug report, post to the Netgate Forum first. The forum is a platform where the problem can be discussed and the specifics required to replicate the issue can be identified.

After discussion and confirmation of a specific, legitimate bug report on the Netgate Forum, please open a ticket in the pfSense Redmine, including a link back to the discussion in question.

Attention

The pfSense Redmine site is not a discussion platform and is never to be used for assistance requests.

What to Include

When submitting a bug report to the pfSense Redmine site, fill out the report completely and include enough supporting information to reproduce the issue.

Use the following guidelines when completing the issue report.

File issues with the base system under pfSense and issues with packages under pfSense Packages.

Note

Not all fields will be available to all users.

Tracker:

Use the appropriate issue tracker type, following these guidelines:

Bug:

Problems, unexpected behavior, crashes, or when the other categories do not apply.

Regression:

A function that worked previously but failed during development or when upgrading to a more recent release.

Feature:

Feature requests or changes in (working) behavior.

Todo:

Tasks or work that need to be completed that are not specifically bugs or features.

Subject:

A brief but complete and accurate description of the problem. If the problem is specific to one page or file, prefix the subject with that page filename.

Example:

Save and Force Update button does not perform any action on ``services_rfc2136_edit.php``
Description:

A full description of the problem. Include any relevant detail, supporting evidence such as log entries, and if possible a complete recount of how to reproduce the bug that includes every necessary step.

Warning

Information in this issue tracker is public! Do not include any personal information such as usernames, passwords, private certificates, keys, e-mail addresses, IP addresses, and so on. In the rare case when such information is helpful in diagnosing a problem, it can be transmitted privately.

  • Please use appropriate formatting, such as <pre> tags around log data or command output. Attach lengthy output in a text file rather than including it inline in the description.

  • Attach files with supporting information, such as logs or crash dumps, if relevant. Check for personal data before attaching files and obfuscate/mask info as needed.

Status:

Leave this as New.

Priority:

Leave this as Normal or set lower for minor issues.

Warning

Higher priorities must only be set by developers when appropriate.

Assignee:

Leave this empty unless directed by a developer to assign it to them directly.

Category:

Pick the closest relevant category for the issue, if possible, or a generic category such as “Web Interface” for GUI issues and “Operating System” for OS issues.

Target Version/Plus Target Version:

Leave this empty unless directed by a developer to assign a specific target.

Warning

Developers may assign a target version after evaluating the issue.

Affected Version:

Pick the version number of the firewall experiencing the issue.

Affected Architecture:

Pick All unless the issue is known to only affect a single architecture.

Leave other fields blank, such as Parent Task, Start/End Date, and so on.

Rejected Issues

Developers may reject an issue for a variety of reasons, including any of the points already noted in this document.

Some possible reasons for rejecting an issue include:

  • The report contained insufficient or incorrect information

  • The report was automatically generated

  • Developers could not reproduce the stated issue

  • The reported issue is not a problem in pfSense software, but an upstream project or dependency

  • The issue is due to an incorrect or invalid configuration

  • The issue only exists when using an unsupported configuration

  • The issue contained a request that was not accepted for development

  • The issue did not contain anything actionable by developers

  • The reported issue is a duplicate, already fixed, or otherwise irrelevant

This is not an exhaustive list; there are many other potential reasons for developers to reject an issue.

If an issue is rejected, do not open a new identical issue for any reason. Users may still leave comments on rejected issues if necessary.