> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nvaccess/nvda/llms.txt
> Use this file to discover all available pages before exploring further.

# Reporting Issues

> How to report bugs, request features, and contribute to NVDA's development

Reporting issues effectively helps improve NVDA for everyone. This guide will help you report bugs and request features in a way that makes it easier for developers to address them.

## Before Reporting

<Steps>
  <Step title="Search existing issues">
    Check if your issue has already been reported on [GitHub Issues](https://github.com/nvaccess/nvda/issues)
  </Step>

  <Step title="Verify the issue">
    Confirm you can reproduce the issue consistently with the latest version of NVDA
  </Step>

  <Step title="Consider discussing first">
    If you're unsure whether something is a bug, open a [GitHub Discussion](https://github.com/nvaccess/nvda/discussions) instead
  </Step>
</Steps>

## Where to Report

<Card title="Report on GitHub" icon="github" href="https://github.com/nvaccess/nvda/issues/new/choose">
  Issues are tracked on GitHub using structured templates
</Card>

<Warning>
  **Security vulnerabilities** should NOT be reported on GitHub. Follow the [security policy](https://github.com/nvaccess/nvda/blob/master/security.md) to report security issues responsibly.
</Warning>

### Special Cases

<CardGroup cols={2}>
  <Card title="Translation Issues" icon="language">
    Report translation problems to the [NVDA Translators list](https://groups.io/g/nvda-translations)
  </Card>

  <Card title="Application/Website Issues" icon="window">
    Consider [reporting to the application/website authors](https://github.com/nvaccess/nvda/blob/master/projectDocs/issues/thirdPartyReporting.md) first
  </Card>
</CardGroup>

## Issue Templates

NVDA uses several GitHub issue templates to ensure all necessary information is provided:

### Bug Reports

<Card title="Bug Report Template" icon="bug" href="https://github.com/nvaccess/nvda/issues/new?template=1-bug_report.yaml">
  Report problems with NVDA's functionality
</Card>

A bug report should include:

* Clear steps to reproduce the issue
* Expected behavior vs. actual behavior
* NVDA version and configuration
* Operating system details
* Log file (if applicable)
* Any relevant files or examples

### Feature Requests

<Card title="Feature Request Template" icon="lightbulb" href="https://github.com/nvaccess/nvda/issues/new?template=2-feature_request.yaml">
  Propose new features or enhancements
</Card>

A feature request should explain:

* The problem or need the feature addresses
* How it would benefit users
* Potential implementation approaches
* Alignment with NVDA's [product vision](/community/product-vision)

### Other Templates

<AccordionGroup>
  <Accordion title="Special Case Issues" icon="question">
    Use the [special case template](https://github.com/nvaccess/nvda/issues/new?template=3-special_case_issue.yaml) for issues that don't fit the bug or feature categories.
  </Accordion>

  <Accordion title="Developer Facing Changes" icon="code">
    The [developer template](https://github.com/nvaccess/nvda/issues/new?template=4-developer_facing_changes.yaml) is for documenting code improvements, API changes, refactoring, and maintenance tasks.
  </Accordion>

  <Accordion title="Add-on Integration Requests" icon="puzzle-piece">
    Use the [add-on integration template](https://github.com/nvaccess/nvda/issues/new?template=5-addon_integration_request.yaml) to propose integrating functionality from existing community add-ons into NVDA core.
  </Accordion>
</AccordionGroup>

## Writing Effective Issue Reports

### Essential Information

<CardGroup cols={2}>
  <Card title="Steps to Reproduce" icon="list-ol">
    Provide clear, numbered steps that anyone can follow to reproduce the issue
  </Card>

  <Card title="Environment Details" icon="computer">
    Include NVDA version, Windows version, and relevant application versions
  </Card>

  <Card title="Expected vs Actual" icon="code-compare">
    Clearly describe what should happen vs. what actually happens
  </Card>

  <Card title="Logs and Files" icon="file">
    Attach NVDA log files and any files needed to reproduce the issue
  </Card>
</CardGroup>

### Tips for Quality Reports

<Accordion title="Include log files">
  NVDA log files are incredibly helpful for debugging. Learn how to [generate and attach log files](https://github.com/nvaccess/nvda/wiki/LogFilesAndCrashDumps).

  If you're getting a crash dump file (`nvda_crash.dmp`), include that as well.
</Accordion>

<Accordion title="Attach necessary files">
  If the issue involves a specific file (Office document, PDF, HTML page), attach it to the issue or provide a link.

  GitHub has [restrictions on file types](https://help.github.com/articles/file-attachments-on-issues-and-pull-requests/), but you can always zip files and attach the archive.
</Accordion>

<Accordion title="Use descriptive titles">
  Write a clear, specific title that summarizes the issue:

  * Good: "NVDA fails to read table headers in Excel 2021 with UIA enabled"
  * Poor: "Excel doesn't work"
</Accordion>

<Accordion title="Describe images">
  While screenshots can be helpful, many NVDA developers are blind. Always describe what the image shows in text.
</Accordion>

## Getting Help

If you're having trouble with the issue template or initial investigation:

<Card title="Ask for Help" icon="hands-helping" href="https://groups.google.com/a/nvaccess.org/g/nvda-users">
  The NVDA Users mailing list is a great place to get assistance
</Card>

## For Developers Reporting Issues

If you're reporting an issue with your application or website:

<Steps>
  <Step title="Include a minimal reproducible sample">
    Provide the smallest possible code or document that demonstrates the issue
  </Step>

  <Step title="Reference specifications">
    Include details about which accessibility specifications aren't being handled correctly
  </Step>

  <Step title="Test with latest NVDA">
    Verify the issue exists in the latest stable or alpha version
  </Step>
</Steps>

## Issue Template Guide

<Card title="Detailed Template Guide" icon="book" href="https://github.com/nvaccess/nvda/blob/master/projectDocs/issues/githubIssueTemplateExplanationAndExamples.md">
  Read the comprehensive guide with examples for filling out GitHub issue templates
</Card>

### Important Notes

<Warning>
  In all but exceptional circumstances, **templates must be completed**. Issues that don't follow a template will likely be closed.
</Warning>

<Note>
  Before filling out a template:

  * Read through it completely in Browse mode
  * Familiarize yourself with [GitHub markdown](https://guides.github.com/features/mastering-markdown/)
  * Use the preview tab to check formatting
</Note>

## After Reporting

Once you've submitted an issue:

1. **Be responsive**: Answer questions and provide additional information if requested
2. **Be patient**: Contributors are volunteers and may take time to respond
3. **Stay subscribed**: GitHub will notify you of updates
4. **Respect priorities**: Issues are prioritized based on severity and impact

## Advanced: Issue Triage

For those interested in helping with issue management:

<Card title="Issue Triage Guide" icon="filter" href="https://github.com/nvaccess/nvda/blob/master/projectDocs/issues/triage.md">
  Learn how to help triage and investigate issues
</Card>