# How to Report a Bug in Switchyard: The Complete Contributor Guide

> Learn how to report a bug in Switchyard effectively. Follow our guide to create a GitHub Issue with a reproducible example and environment details for quick resolution.

- Repository: [NVIDIA-NeMo/Switchyard](https://github.com/NVIDIA-NeMo/Switchyard)
- Tags: how-to-guide
- Published: 2026-08-23

---

**To report a bug in Switchyard, open a GitHub Issue using the Bug report template, provide a minimal reproducible example under 30 lines, and include your environment details and full traceback logs.**

If you encounter unexpected behavior in the NVIDIA-NeMo/Switchyard repository, submitting a detailed bug report helps maintainers diagnose and resolve issues efficiently. Understanding how to report a bug in Switchyard ensures your issue receives prompt attention and actionable feedback. This guide walks through the exact process defined in the project's [`.github/ISSUE_TEMPLATE/bug_report.md`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/.github/ISSUE_TEMPLATE/bug_report.md) and [`CONTRIBUTING.md`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/CONTRIBUTING.md) files.

## Search Existing Issues Before Reporting

Before creating a new issue, search the existing Switchyard issue tracker to confirm the problem has not already been reported. Duplicate reports fragment discussion and slow down the triage process. If you find a related issue, add your reproduction details or environment information to the existing thread rather than opening a duplicate.

## Open a Bug Report Using the GitHub Template

Switchyard uses GitHub Issues exclusively for bug tracking. Navigate to the repository issue tracker at `https://github.com/NVIDIA-NeMo/Switchyard/issues` and click **“New issue.”** Select the **Bug report** template to ensure you include all required fields.

The template in [`.github/ISSUE_TEMPLATE/bug_report.md`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/.github/ISSUE_TEMPLATE/bug_report.md) requires the following information:

- **Title** – A concise summary of the problem that helps maintainers identify the issue category at a glance.
- **Description** – Explain what you expected to happen versus what actually occurred.
- **Steps to reproduce** – A minimal, reproducible snippet or command line that triggers the bug consistently.
- **Environment** – Your operating system, Python version, and Switchyard version obtained via `pip show switchyard`.
- **Logs / Tracebacks** – The full error output and relevant log files. Never paste API keys or secrets.
- **Additional context** – Links to related PRs, external documentation, or other issues that provide background.

## Create a Minimal Reproducible Example

A minimal reproducible example (MRE) isolates the failure in the fewest lines of code possible, ideally fewer than 30 lines. This eliminates variables unrelated to the bug and allows maintainers to verify the issue quickly. For Python-side bugs, focus on the entry points in [`switchyard/libsy/algorithms.py`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/switchyard/libsy/algorithms.py), which serves as a common router for many library functions.

Below is a template for a Python MRE that you can paste into the issue template:

```python
import switchyard
from switchyard.libsy import algorithms

def main():
    # Replace with the actual failing call

    try:
        result = algorithms.some_algorithm(param=42)
        print("Result:", result)
    except Exception as e:
        print("Caught exception:", e)
        raise

if __name__ == "__main__":
    main()

```

If the bug originates from the Rust implementation, provide a small Rust snippet that triggers the problem using the `switchyard-rust` crate. Compile and test your example independently to confirm it reproduces the error before submitting.

## Document Your Environment

Accurate environment details are critical for reproduction. Run `pip show switchyard` to capture the installed version, or check [`switchyard/__init__.py`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/switchyard/__init__.py) directly for the version string. Include your operating system, Python version, and any relevant environment variables (with sensitive values redacted). For bugs involving routing algorithms, note whether you are using the pure Python implementation or the Rust backend.

## Label and Submit the Issue

If you have repository permissions, add the **bug** label along with component-specific labels such as **python**, **rust**, or **routing**. These labels appear in the issue tracker and help maintainers triage efficiently. After verifying that no secrets or proprietary data appear in your logs or code snippets, click **“Submit new issue.”**

## Follow Up and Contribute Fixes

Monitor the issue thread for clarification requests from maintainers. Timely responses keep the investigation moving forward. If you develop a fix, open a pull request that references the issue number in the description using the format `Fixes #123` to automatically link the resolution.

## Summary

- **Search first** to avoid duplicate reports in the NVIDIA-NeMo/Switchyard tracker.
- **Use the template** at [`.github/ISSUE_TEMPLATE/bug_report.md`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/.github/ISSUE_TEMPLATE/bug_report.md) to structure your report.
- **Provide an MRE** under 30 lines that isolates the failure, targeting [`switchyard/libsy/algorithms.py`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/switchyard/libsy/algorithms.py) for Python bugs.
- **Include environment data** from `pip show switchyard` or [`switchyard/__init__.py`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/switchyard/__init__.py), plus full tracebacks.
- **Label appropriately** with `bug` and component tags if permissions allow.
- **Follow up** on questions and reference the issue in any related pull requests.

## Frequently Asked Questions

### Where can I find the official bug report template in Switchyard?

The official template is located at [`.github/ISSUE_TEMPLATE/bug_report.md`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/.github/ISSUE_TEMPLATE/bug_report.md) in the repository root. When you click **“New issue”** in the GitHub interface, selecting the Bug report option automatically populates the description field with this template.

### What constitutes a minimal reproducible example for Switchyard bugs?

A minimal reproducible example is a self-contained script, typically under 30 lines, that triggers the bug without external dependencies or proprietary data. For Python issues, import from `switchyard.libsy.algorithms` and demonstrate the exact call that raises an exception. For Rust issues, provide a small snippet using the `switchyard-rust` crate.

### How do I safely check and report my Switchyard version?

Run `pip show switchyard` in your terminal to display the installed version, or inspect [`switchyard/__init__.py`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/switchyard/__init__.py) where the version is defined. When reporting, include the version string but ensure you remove any sensitive environment variables or API keys from your terminal output before pasting it into the issue.

### Can I submit security vulnerabilities through public GitHub Issues?

The analysis provided does not specify a security reporting policy. For security-related bugs, check [`CONTRIBUTING.md`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/CONTRIBUTING.md) or the repository's security documentation for private disclosure channels. Public issues should never contain exploit details or vulnerability proofs that could compromise users.