Bug Reports

Relevant source files

This page documents how to file effective bug reports for the TypeScript compiler. Bug reports help the TypeScript team identify and fix defects in the compiler, language service, and related tooling.

For feature requests, see Feature Requests. For issues with DOM/WebWorker type definitions, see Library Definition Issues. For module resolution problems, see Module Resolution Issues.

🚨 Critical Maintenance Notice

The microsoft/TypeScript repository is currently in maintenance mode. TypeScript 6.0 is the final JavaScript-based release. Development has transitioned to the Go-based rewrite at microsoft/typescript-go.

Accepted Bug Categories: Only bugs meeting these strict criteria will be addressed in this repository:

Crashes introduced in 5.9 or 6.0 that also repro in 7.0 (Go version).
Security issues.
Language service crashes impacting mainline usage.
Serious regressions from 5.9 impacting a large proportion of users.

Sources: CONTRIBUTING.md5-6 README.md31-39 AGENTS.md1-7

Purpose and Scope

Bug reports in the TypeScript repository track reproducible defects in TypeScript's behavior. A bug report must describe:

Incorrect compiler diagnostics (false positives or false negatives).
Type checking failures or incorrect type inference.
Incorrect JavaScript output from the emitter.
Language service crashes or incorrect IDE behavior.
Other reproducible defects in TypeScript tooling.

Sources: CONTRIBUTING.md56-62 README.md42

Prerequisites Before Filing

1. Check the FAQ

The TypeScript FAQ answers many common questions about TypeScript behavior. Issues asking questions already answered in the FAQ will be closed without elaboration.

Many long-standing behaviors are documented in the FAQ's "Common Bugs That Aren't Bugs" section. For example, narrowing behaviors in callbacks are intentional and documented in specific templates to prevent duplicate reports.

Sources: CONTRIBUTING.md33-37 .github/ISSUE_TEMPLATE/bug_report.yml31 .github/ISSUE_TEMPLATE/types-not-correct-in-with-callback.md1-11

2. Search for Duplicates

Before creating a new issue, search existing issues thoroughly:

Search strategies:

Don't restrict searches to only open issues (closed issues may be duplicates).
Search for synonyms (e.g., "interface" issues often affect "type" and "class" too).
Search for the specific title of the issue you are about to log.
For crashes, search for function names from the top of the stack trace.

Sources: CONTRIBUTING.md39-49 .github/ISSUE_TEMPLATE/bug_report.yml7

3. Questions vs Bugs

The issue tracker is for bugs and suggestions. If you have a question, use:

Sources: CONTRIBUTING.md50-54 README.md44-46

Bug Report Template Structure

Bug reports use a structured YAML template defined in .github/ISSUE_TEMPLATE/bug_report.yml.

Required Fields

Search Terms

List keywords used when searching. This helps others find the issue. Examples: "function inference any", "jsx attribute spread", "ts2822".

Sources: .github/ISSUE_TEMPLATE/bug_report.yml11-23

Version and Regression Information

Specify when the bug started. Use the line that best applies:

This changed between versions X and Y.
This changed in commit or PR Z.
This is the behavior in every version I tried.

Try the nightly build (npm install typescript@next) or the Playground to see if it is already fixed. For regressions, use every-ts to find the specific change.

Sources: .github/ISSUE_TEMPLATE/bug_report.yml25-46 CONTRIBUTING.md59-63

Playground Link

A link to a TypeScript Playground "Share" link showing the behavior. The Playground supports versions back to 3.3. Repos are a last resort as they are slower to investigate.

Sources: .github/ISSUE_TEMPLATE/bug_report.yml48-59

Code Sample

The code and the Playground code should be identical.

Keep it short: Most bugs can be shown in 20-30 lines.
No external libraries: Issues with libraries are often type definition issues, not compiler bugs.
Apparent incorrectness: The error should be obvious.

Sources: .github/ISSUE_TEMPLATE/bug_report.yml61-85

Specialized Reporting

Module Resolution Issues

Module resolution is complex and often a misconfiguration. Before reporting, use Are The Types Wrong?. Reports require:

A cloneable demo repository.
Output of tsc --showConfig.
Output of tsc --traceResolution.
package.json for both importing and target modules.

Sources: .github/ISSUE_TEMPLATE/module_resolution.yml1-104

Library Definition Issues

For issues in lib.d.ts (e.g., lib.es6.d.ts):

Check if your lib setting in tsconfig.json is correct (e.g., lib: ["es2020"]).
For DOM issues, file them at TypeScript-DOM-lib-generator

Sources: .github/ISSUE_TEMPLATE/lib_change.yml1-57

Contribution Policy for Bug Fixes

Due to the maintenance mode, the project does not accept bulk, agent-driven contributions.

AI tools are allowed for individual PRs if the contributor understands the change and discloses AI use.
Automated summaries or comments are strictly prohibited.
PRs for non-critical bugs will be closed with a pointer to the maintenance policy.

Sources: CONTRIBUTING.md7-30 AGENTS.md9-27