# How to Report a Bug in Freebuff: Complete Guide to Issue Templates and Best Practices > Learn how to report a bug in Freebuff effectively. Use GitHub issue templates, provide detailed steps, and follow best practices for quick resolution. Protect your credentials. - Repository: [Codebuff/freebuff](https://github.com/CodebuffAI/freebuff) - Tags: how-to-guide - Published: 2026-08-21 --- **To report a bug in freebuff, create a GitHub issue using the Bug template for functional defects or the Support template for account-related problems, ensuring you provide a descriptive title, detailed reproduction steps, and relevant product context while never exposing API keys or credentials.** Reporting bugs effectively is essential for improving the **CodebuffAI/freebuff** ecosystem and ensuring maintainers can diagnose issues efficiently. Whether you encounter model limits, session counting errors, or unexpected behavior in the CLI or Desktop applications, following the repository's structured workflow increases the likelihood of a quick resolution. This guide walks you through the exact process defined in the freebuff source code to help you submit high-quality bug reports. ## Choosing the Correct Issue Template The freebuff repository provides specialized templates to route different problems to the appropriate team. According to [`CONTRIBUTING.md`](https://github.com/CodebuffAI/freebuff/blob/main/CONTRIBUTING.md), selecting the right template is the first critical step in the reporting process. ### Use the Bug Template for Functional Defects For issues involving **model limits**, **session counting**, or any **functional defect** in the application logic, select the **Bug** template when creating your issue. The maintainers explicitly state that such problems "are a bug and we do want the issue" as documented in [`CONTRIBUTING.md`](https://github.com/CodebuffAI/freebuff/blob/main/CONTRIBUTING.md) (lines 108-114). This template prompts you for technical details like reproduction steps and error logs. ### Use the Support Template for Account and Quota Issues If your problem relates to account access, billing, or quota limitations, use the **Support** template defined in [`.github/ISSUE_TEMPLATE/support.yml`](https://github.com/CodebuffAI/freebuff/blob/main/.github/ISSUE_TEMPLATE/support.yml) (lines 1-14). This YAML configuration is specifically designed for operational issues rather than code defects, ensuring your request reaches the appropriate support workflow. ## Structuring Your Bug Report Once you've selected the correct template, providing comprehensive information is crucial. The automated triage system verifies structural requirements within seconds of submission, so adherence to these guidelines prevents immediate rejection. ### Write a Descriptive Title Avoid generic titles like "WIP" or one-word stubs, which are automatically rejected per [`CONTRIBUTING.md`](https://github.com/CodebuffAI/freebuff/blob/main/CONTRIBUTING.md) (lines 63-66). Your title should accurately summarize the defect, such as "Session counter resetting to zero when using deepseek-v4-pro model" rather than "bug help" or "broken." ### Include Essential Diagnostic Information A complete bug report requires four specific components: - **Expected behavior**: What the system should have done - **Observed behavior**: The exact error message or unexpected output - **Reproduction steps**: Specific commands run, models used, and configuration details - **Minimal code snippet**: A condensed example or repository link that triggers the bug ### Specify Product Context Clearly indicate which **freebuff product** you're using—CLI, Desktop, Cloud, or another variant—along with the **model version** (for example, `deepseek-v4-pro`). This context helps maintainers route the issue to engineers familiar with that specific component. ## Security Best Practices Never paste API keys, authentication tokens, or personal account details in your issue. The support template explicitly warns against exposing secrets in [`.github/ISSUE_TEMPLATE/support.yml`](https://github.com/CodebuffAI/freebuff/blob/main/.github/ISSUE_TEMPLATE/support.yml) (lines 45-48). If logs contain sensitive data, sanitize them before submission or reference the specific error patterns without including the actual credentials. ## What Happens After Submission After you submit the issue, an automated bot performs immediate validation checks to verify title formatting, description completeness, and scope alignment as defined in [`CONTRIBUTING.md`](https://github.com/CodebuffAI/freebuff/blob/main/CONTRIBUTING.md) (lines 57-73). If your report passes these structural checks, the system applies labels such as `type:bug` and routes it to a maintainer for investigation. Valid bug reports may eventually be merged into the private source repository after review. ## Summary - **Select the Bug template** for functional defects like model limits and session counting errors, and the **Support template** for account-related issues. - **Craft specific titles** that describe the problem; avoid placeholder text like "WIP" to prevent automatic rejection. - **Provide complete context** including expected vs. observed behavior, reproduction steps, product variant (CLI/Desktop/Cloud), and model version. - **Sanitize all submissions** to ensure no API keys or personal credentials appear in public issues. - **Expect automated triage** within seconds of submission, followed by maintainer review for reports meeting structural requirements. ## Frequently Asked Questions ### What is the difference between the Bug and Support templates in freebuff? The Bug template handles technical defects such as model limits, session counting errors, and application crashes, while the Support template addresses operational issues like account access, billing problems, and quota management. Choosing the correct template ensures your issue reaches the appropriate team within the CodebuffAI/freebuff repository. ### Can I report a bug without using the provided templates? No, the repository requires structured input to pass automated validation checks. According to [`CONTRIBUTING.md`](https://github.com/CodebuffAI/freebuff/blob/main/CONTRIBUTING.md), issues with generic titles or insufficient descriptions are rejected automatically. Using the templates ensures you provide all necessary diagnostic information the maintainers need to reproduce and fix the bug. ### How quickly will my bug report be reviewed? An automated bot triages issues within seconds of submission to verify structural requirements such as title quality and description completeness. If your report passes these checks and receives the `type:bug` label, a maintainer will review it, though resolution timelines depend on complexity and current backlog. ### What should I do if my bug involves sensitive data or security vulnerabilities? Do not post API keys, tokens, or personal account details in public issues, as explicitly warned in [`.github/ISSUE_TEMPLATE/support.yml`](https://github.com/CodebuffAI/freebuff/blob/main/.github/ISSUE_TEMPLATE/support.yml) (lines 45-48). For security vulnerabilities, check if the repository provides a private disclosure method or security policy. For data-sensitive bugs, describe the error patterns and reproduction steps without including the actual sensitive values.