fastmcp/.github/ISSUE_TEMPLATE/bug.yml

name: 🐛 Bug Report
description: Report a bug or unexpected behavior in FastMCP
labels: [bug, pending]

body:
  - type: markdown
    attributes:
      value: |
        Thanks for reporting a bug!

        A good bug report is one of the most valuable contributions you can make — see [CONTRIBUTING.md](../../CONTRIBUTING.md). If the fix is straightforward, a PR is also welcome.

        ### Before you submit

        - Make sure you're testing on the **latest version** of FastMCP — many issues are already fixed in newer releases
        - Check if someone else has **already reported this** or if it's been fixed on the main branch
        - You **must** include a copy/pasteable, properly formatted MRE (minimal reproducible example) or your issue may be closed without response
        - **The ideal issue is a clear problem description and an MRE — that's it.** If you've done genuine investigation and have a non-obvious insight into the root cause, include it. But please don't speculate or ask an LLM to generate a diagnosis. We have LLMs too, and an incorrect analysis is harder to work with than none at all.
        - **Keep it short.** A clear description plus a concise MRE is ideal — aim to fit in a single screen. Issues that include unsolicited root cause analysis, proposed fixes, or multi-section diagnostic writeups will be labeled `too-long` and not triaged until condensed.
        - **Using an LLM?** Great — but it must follow these guidelines. Generic LLM output that ignores our contributing conventions will be closed. See [CONTRIBUTING.md](../../CONTRIBUTING.md).

  - type: textarea
    id: description
    attributes:
      label: What happened?
      description: |
        Describe the bug in a few sentences. What did you do, what happened, and what did you expect instead?

        Do NOT include root cause analysis, proposed fixes, or diagnostic writeups — just describe the problem.
    validations:
      required: true

  - type: textarea
    id: example
    attributes:
      label: Example Code
      description: >
        If applicable, please provide a self-contained,
        [minimal, reproducible example](https://stackoverflow.com/help/minimal-reproducible-example)
        demonstrating the bug. If possible, your example should be a single-file script.

      placeholder: |
        import asyncio
        from fastmcp import FastMCP, Client

        mcp = FastMCP()

        async def demo():
            async with Client(mcp) as client:
                ... # show the bug here

        if __name__ == "__main__":
            asyncio.run(demo())
      render: Python

  - type: textarea
    id: version
    attributes:
      label: Version Information
      description: |
        Please tell us about your FastMCP version, MCP version, Python version, and OS, as well as any other relevant details about your environment.

        To get the basic information, run the following command in your terminal and paste the output below:

        ```bash
        fastmcp version --copy
        ```
      render: Text
    validations:
      required: true