Skip to main content

​
Overview

The Terraform Core team follows a structured bug triage process to respond quickly to issue reports. The goal is to either get bugs ready for engineering to fix or close them with a clear explanation if the team can’t help.

​
Bug Report Lifecycle

Every bug report goes through these stages:
  1. New: Initial filtering and categorization
  2. Unreproduced: Clarification and reproduction
  3. Confirmed: Verified and reproducible
  4. Explained: Root cause identified
  5. Fixed: PR merged or issue closed

​
Stage 1: New Issues

Newly created issues require initial filtering:

​
What Happens

  • Label backends, provisioners, and providers to route to correct teams
  • Point help requests to the community forum and close the issue
  • Close reports against old, unsupported versions
  • Prompt users for additional information if reproduction case is incomplete

​
Labels Applied

  • new - Fresh issue not yet triaged
  • waiting-response - Needs user response during initial filtering
  • Backend/provisioner labels for routing

​
When Complete

The new label is removed after initial filtering. High-impact issues may be assigned to a milestone immediately.
View newly created issues awaiting triage.

​
Stage 2: Unreproduced Issues

Core team members attempt to reproduce the issue.

​
If Reproducible Immediately

The issue is labeled confirmed and moves to the next stage.

​
If Not Reproducible

  1. Label as waiting for reproduction
  2. Correspond with reporter to describe what’s needed
  3. When team member reproduces, label as confirmed

​
Requirements for Confirmation

  • Clear reproduction case: Anyone should be able to reproduce without inventing details
  • Complete information: All relevant configuration, versions, and environment details
  • Minimal example: Smallest possible configuration that demonstrates the issue
View unreproduced issues needing clarification.

​
Stage 3: Confirmed Issues

Verified, reproducible issues ready for analysis.

​
What Happens

The team either:
  1. Explains as expected behavior
    • Label as working as designed
    • Explain why the behavior is intended
    • Close the issue
  2. Locates the defect
    • Identify root cause in codebase
    • Document findings on the issue
    • Label as explained
    • Sometimes skip directly to submitting a PR

​
Priority Handling

Confirmed crashes are considered high impact and should be prioritized.
View confirmed crashes requiring urgent attention.
View all confirmed issues awaiting analysis.

​
Stage 4: Explained Issues

Issues with identified root causes ready for fixes.

​
What Happens

  1. Create a pull request to fix the issue
  2. Issues expected to be fixed in upcoming releases are assigned to milestones
  3. Complex issues may be labeled pending project if they require significant work
View explained issues ready for PRs.

​
GitHub Labels

​
Triage Labels

LabelDescription
newNew issue not yet triaged
waiting for reproductionUnable to reproduce without more information
waiting-responseAwaiting user response
confirmedA core team member has reproduced this issue
explainedRoot cause described in the issue

​
Resolution Labels

LabelDescription
working as designedBehavior is intended, closed as explained
not reproducibleCould not generate a reproduction case
duplicateAnother issue already tracks this problem
pending projectRequires a significant project to fix

​
Priority Labels

LabelDescription
crashTerraform crashes or panics
regressionPreviously working functionality broken
Milestone assignmentIndicates target release for fix

​
Component Labels

  • backend/* - State storage backend issues
  • provisioner/* - Provisioner issues
  • terraform-cloud - HCP Terraform integration
  • documentation - Documentation fixes needed

​
Handling Stale Issues

​
Lack of Response

When issues are labeled waiting-response or waiting for reproduction for more than 30 days:
  1. Team uses judgment to either:
    • Close the issue with a polite message
    • Prompt the reporter again
  2. If 30 more days pass without response:
    • Issue is closed
    • Message invites future submission of needed information
This process helps the team and community contributors find actionable bug reports.

​
Filing a Good Bug Report

To help your bug report move quickly through triage:

​
Include All Information

  • Terraform version: Output of terraform version
  • Operating system: OS and version
  • Terraform configuration: Complete, minimal reproduction case
  • Expected behavior: What should happen
  • Actual behavior: What actually happens
  • Steps to reproduce: Clear, numbered steps
  • Additional context: Relevant logs, screenshots, or environment details

​
Use the Issue Template

The bug report template requests all necessary information. Fill in every section.

​
Provide Minimal Reproduction

Create the smallest possible configuration that demonstrates the issue: 
# Good: Minimal example
resource "null_resource" "example" {
  triggers = {
    timestamp = timestamp()
  }
}

# Bad: Complete production configuration with 50 resources

​
Check for Duplicates

Search existing issues before filing a new one. If you find a duplicate:
  • Add a 👍 reaction to the original issue
  • Comment only if you have new information
  • Don’t create a new issue

​
Test on Latest Version

Verify the bug exists on the latest Terraform release. Bugs in old versions may already be fixed.

​
What to Avoid

Don’t ask for help: Use HashiCorp Discuss for usage questions.
Don’t report provider issues: Report these in the provider’s repository, not Terraform Core.
Don’t bump issues: Commenting “any update?” doesn’t help and creates noise. Use 👍 reactions instead.

​
Milestones

​
Milestone Naming

  • X.Y.x: Issues to be fixed during that minor release lifecycle
  • X.Y.0: Issues that must be fixed before that major/minor release
Examples:
  • 1.9.x - Fixed in any 1.9.x patch release before 1.10.0 RC1
  • 1.10.0 - Must be fixed before 1.10.0 RC1 ships

​
Milestone Priority

Issues assigned to milestones are considered higher priority than those without milestones.

​
Special Categories

​
Backend Issues

Backend maintainers are highlighted for participation. See State Storage Backends for maintainer expectations.

​
Documentation Issues

Confirmed documentation needs are labeled documentation and can be fixed by community contributors. View confirmed documentation issues.

​
Pending Projects

Some confirmed bugs require significant projects to fix and are labeled pending project. View issues pending major projects.

​
Community Contributions

You can help with bug triage by:
  1. Reproducing issues: Test reported bugs and comment with your results
  2. Providing minimal examples: Help reporters create minimal reproductions
  3. Identifying duplicates: Link to existing issues that cover the same bug
  4. Fixing explained bugs: Submit PRs for bugs with identified root causes
Look for explained issues without assigned PRs - these are great opportunities to contribute fixes.

​
Maintainer Involvement

For code with listed maintainers in CODEOWNERS:
  • Maintainers are highlighted on relevant PRs
  • Expected to review code before core team merges
  • No guaranteed response time (maintainers may be unavailable)
  • Community members can volunteer as maintainers

​
Next Steps

Report a Bug

File a new bug report with the issue template

Pull Requests

Learn how to submit fixes for confirmed bugs

Contributing Overview

Read the full contributing guidelines

Build docs developers (and LLMs) love

Get started for freeTalk to us