# How to Report a Bug or Issue in Plane: Complete Guide

> Learn how to report bugs in Plane. Search existing issues and use the GitHub bug report template with a minimal reproduction scenario for quick resolution.

- Repository: [Plane/plane](https://github.com/makeplane/plane)
- Tags: how-to-guide
- Published: 2026-06-20

---

**Report bugs in Plane by searching existing issues first, then using the GitHub bug report template at [`.github/ISSUE_TEMPLATE/--bug-report.yaml`](https://github.com/makeplane/plane/blob/main/.github/ISSUE_TEMPLATE/--bug-report.yaml) with a minimal reproduction scenario.**

The makeplane/plane repository uses a structured workflow to ensure every bug report is actionable and reproducible. Following the official contribution guidelines and the built-in issue template helps maintainers triage and resolve issues efficiently.

## Prerequisites and Initial Checks

Before creating a new issue, verify that the bug hasn’t already been reported.

### Search Existing Issues

Browse open and closed issues in the repository to avoid duplicates. The [`CONTRIBUTING.md`](https://github.com/makeplane/plane/blob/main/CONTRIBUTING.md) file explicitly requires this step, stating that contributors should search existing bugs and discussions before submitting a new report. This prevents fragmentation and helps you find potential workarounds while the fix is pending.

## Creating a Minimal Reproduction

Plane requires a **minimal, reproducible scenario** that demonstrates the problem. According to the contribution guidelines in [`CONTRIBUTING.md`](https://github.com/makeplane/plane/blob/main/CONTRIBUTING.md), your reproduction must include:

- The exact version of Plane you are running (e.g., `v0.20.1-dev`)
- Versions of any third-party libraries or dependencies involved
- Step-by-step instructions that reliably trigger the bug
- Environment details (self-hosted vs. cloud, browser type, etc.)

Without this information, maintainers cannot verify the issue, which delays the triage process.

## Submitting the Bug Report

Once you have gathered the necessary details, use the official GitHub issue template to standardize your report.

### Using the GitHub Issue Template

Navigate to the **New Issue** page and select the **Bug report** template. The direct URL pre-populates assignees and labels:

```

https://github.com/makeplane/plane/issues/new?assignees=srinivaspendem%2Cpushya22&labels=%F0%9F%90%9Bbug&projects=&template=--bug-report.yaml&title=%5Bbug%5D%3A+

```

This template is defined in [`.github/ISSUE_TEMPLATE/--bug-report.yaml`](https://github.com/makeplane/plane/blob/main/.github/ISSUE_TEMPLATE/--bug-report.yaml) and automatically assigns the issue to `srinivaspendem` and `pushya22` with the `🐛bug` label.

### Required Fields in the Template

The YAML template enforces structured input through the following fields:

- **Is there an existing issue for this?** – Confirmation checkbox to prevent duplicates
- **Current behavior** – A clear description of what is happening
- **Expected behavior** – What you anticipated should occur instead
- **Steps to reproduce** – Numbered steps that trigger the bug
- **Environment** – Dropdown selections for:
  - Deployment type (Production/Deploy preview)
  - Browser (Chrome, Firefox, Safari, etc.)
  - Variant (Self-hosted vs. Plane Cloud)
- **Version** – The specific Plane release where the bug occurs

## Example Bug Report

Below is a complete example of the markdown content you would provide in the template body:

```markdown
**Current behavior**  
When I click the "Create Cycle" button, the UI throws a `500 Internal Server Error` and the network request in the devtools console shows `POST /api/cycles/` returning a 500.

**Expected behavior**  
The button should open the "Create Cycle" dialog and successfully create a new cycle.

**Steps to reproduce**
1. Log in as an admin.
2. Navigate to the "Cycles" view.
3. Click the **Create Cycle** button.
4. Observe the error.

**Environment**
- **Variant:** Self‑hosted
- **Browser:** Google Chrome
- **Version:** v0.20.1-dev

```

## After Submission

Once submitted, the Plane team will verify the reproduction steps and begin triage. If maintainers request additional information—such as server logs, screenshots, or a link to a Gist—reply promptly to keep the issue active. Keep the issue description updated if you discover new details or workarounds.

## Summary

- **Search first**: Check existing issues in `makeplane/plane` before filing duplicates
- **Reproduce minimally**: Provide exact steps, version numbers, and environment details as mandated in [`CONTRIBUTING.md`](https://github.com/makeplane/plane/blob/main/CONTRIBUTING.md)
- **Use the template**: File bugs using [`.github/ISSUE_TEMPLATE/--bug-report.yaml`](https://github.com/makeplane/plane/blob/main/.github/ISSUE_TEMPLATE/--bug-report.yaml) to ensure all required fields are completed
- **Engage actively**: Respond to maintainer requests for additional information to expedite resolution

## Frequently Asked Questions

### Where is the bug report template located in the Plane repository?

The template is stored at [`.github/ISSUE_TEMPLATE/--bug-report.yaml`](https://github.com/makeplane/plane/blob/main/.github/ISSUE_TEMPLATE/--bug-report.yaml) in the `preview` branch. This YAML file defines the structured form that appears when you select "Bug report" from the new issue menu, including dropdowns for environment selection and required fields for reproduction steps.

### What information is mandatory when reporting a bug in Plane?

You must confirm you have searched for existing issues, provide the current behavior versus expected behavior, list step-by-step reproduction instructions, specify your environment (browser, deployment type), and state the Plane version. The [`CONTRIBUTING.md`](https://github.com/makeplane/plane/blob/main/CONTRIBUTING.md) file explicitly states that a minimal reproduction scenario is mandatory for the team to investigate.

### Who gets assigned when I submit a bug report?

When you use the bug report template, the issue is automatically assigned to `srinivaspendem` and `pushya22` with the `🐛bug` label. These assignees handle triage and prioritize the issue based on severity and reproducibility.

### Can I report bugs without using the official template?

While you can technically open a blank issue, the Plane maintainers strongly prefer using the structured template. The [`CONTRIBUTING.md`](https://github.com/makeplane/plane/blob/main/CONTRIBUTING.md) guidelines and the [`.github/ISSUE_TEMPLATE/--bug-report.yaml`](https://github.com/makeplane/plane/blob/main/.github/ISSUE_TEMPLATE/--bug-report.yaml) file are designed to capture essential debugging information upfront, which significantly reduces the time required for maintainers to reproduce and fix the issue.