Skip to main content

​
Overview

Issues are an important part of the Node.js development process. This guide explains how to effectively submit bug reports, request features, and help triage issues.

​
Asking for General Help

Because the level of activity in the nodejs/node repository is so high, questions or requests for general help using Node.js should be directed at the Node.js help repository.
The main nodejs/node repository is for bug reports and feature development. For general help with Node.js, use the help repository or community forums.

​
Discussing Non-Technical Topics

Discussion of non-technical topics (such as intellectual property and trademark) should be directed to the Technical Steering Committee (TSC) repository.

​
Submitting a Bug Report

​
Using Issue Templates

When opening a new issue in the nodejs/node issue tracker, users will be presented with a choice of issue templates. If you believe that you have uncovered a bug in Node.js, please fill out the Bug Report template to the best of your ability.
Don’t worry if you cannot answer every detail in the template; just fill in what you can.

​
Critical Information

The two most important pieces of information we need in order to properly evaluate the report are:
  1. Description of the behavior you are seeing
  2. Simple test case we can use to recreate the problem
If we cannot recreate the issue, it becomes impossible for us to fix.

​
Creating a Minimal Test Case

In order to rule out the possibility of bugs introduced by userland code, test cases should be limited, as much as possible, to using only Node.js APIs. If the bug occurs only when you’re using a specific userland module, there is a very good chance that either:
  • (a) The module has a bug, or
  • (b) Something in Node.js changed that broke the module

​
Best Practices

Create a Minimal, Complete, and Verifiable example:
  • Minimal: Use as little code as possible to reproduce the issue
  • Complete: Provide all parts needed to reproduce the problem
  • Verifiable: Test the code you’re about to provide to make sure it reproduces the problem
See How to create a Minimal, Complete, and Verifiable example for more guidance.

​
Bug Report Example

**Version**: v20.0.0
**Platform**: macOS 13.2, Apple M1
**Subsystem**: fs

**Description**:
When calling `fs.readFileSync()` with a specific path, the function
throws an unexpected error.

**Minimal reproduction**:
```javascript
const fs = require('fs');
const data = fs.readFileSync('/path/to/file.txt');
// Error: ENOENT: no such file or directory
Expected behavior: File should be read successfully Actual behavior: Error thrown even though file exists 

## Triaging Bug Reports

### Purpose of Triaging

The objective of helping with triaging issues (in core and help repos) is to help reduce the issue backlog and keep the issue tracker healthy, while enabling newcomers another meaningful way to get engaged and contribute.

### Becoming a Triager

Anyone with a reasonable understanding of Node.js programming and the project's GitHub organization plus a few contributions to the project (commenting on issues or PRs) can apply for and become a triager.

#### How to Apply

Open a PR on the README.md of the project with:
1. A request to be added as a triager
2. The motivation for becoming a triager
3. Agreement on reading, understanding, and adhering to the project's [Code of Conduct](https://github.com/nodejs/admin/blob/HEAD/CODE_OF_CONDUCT.md)

### Triager Permissions

The triage role enables the ability to carry out the most common triage activities, such as:
- Applying labels
- Closing/reopening issues
- Assigning issues

For more information on the roles and permissions, see ["Permission levels for repositories owned by an organization"](https://docs.github.com/en/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization#permission-levels-for-repositories-owned-by-an-organization).

## Triaging Guidelines

When triaging issues and PRs:

### Show Patience and Empathy

<Tip>
  Be especially patient and welcoming to first-time contributors.
</Tip>

- Welcome newcomers
- Provide constructive feedback
- Assume good intentions
- Guide contributors through the process

### Deal with Spam

<Warning>
  Show no patience towards spam or trolls. Close the issue without interacting with it and report the user to the moderation repository.
</Warning>

### Request More Information

If you're not able to reproduce an issue:
- Leave a comment asking for more information
- Add the `needs more info` label
- Be specific about what information is needed

### Closing Issues

Ideally, issues should be closed only when they have been:
- Fixed and merged (for bugs)
- Answered (for questions)
- Implemented (for features)

<Info>
  Closing an issue (or PR) earlier can be seen as dismissive from the point of view of the reporter/author. Always try to communicate the reason for closing the issue/PR.
</Info>

## Discussion Process

Once an issue has been opened, it is common for there to be discussion around it. Some contributors may have differing opinions about the issue, including whether the behavior being seen is a bug or a feature.

This discussion is part of the process and should be:
- **Focused**: Stay on topic
- **Helpful**: Provide actionable feedback
- **Professional**: Maintain respectful discourse

## Common Labels

### Issue Type Labels
- `bug`: Confirmed bugs
- `feature request`: Requests for new functionality
- `question`: Questions about Node.js
- `documentation`: Documentation improvements

### Status Labels
- `needs more info`: Issue needs additional information
- `good first issue`: Suitable for newcomers
- `confirmed-bug`: Bugs that have been verified
- `stalled`: Issues that have become inactive

### Priority Labels
- `critical`: Critical issues requiring immediate attention
- `high priority`: Important issues
- `low priority`: Nice-to-have improvements

## Feature Requests

When submitting feature requests:

1. **Search existing issues** to avoid duplicates
2. **Describe the use case** clearly
3. **Explain the benefits** to the community
4. **Consider alternatives** and discuss trade-offs
5. **Be open to feedback** and discussion

<Note>
  Not all feature requests will be accepted. The TSC makes final decisions on whether features align with the project's goals and technical direction.
</Note>

## Resources

- [Node.js help repository](https://github.com/nodejs/help/issues) - For general help
- [TSC repository](https://github.com/nodejs/TSC/issues) - For governance discussions
- [Issue tracker](https://github.com/nodejs/node/issues) - For bugs and features
- [Code of Conduct](https://github.com/nodejs/admin/blob/HEAD/CODE_OF_CONDUCT.md)

## Related Guides

- [Pull Requests](/contributing/pull-requests) - How to submit code changes
- [Code of Conduct](/contributing/code-of-conduct) - Community guidelines
- [Collaborator Guide](/contributing/collaborator-guide) - For project collaborators