# How to Report a Bug in Supertonic: A Complete Guide for Contributors

> Learn how to report a bug in Supertonic. Follow our guide to submit a clear GitHub issue with reproducible steps for faster resolution.

- Repository: [Supertone Inc./supertonic](https://github.com/supertone-inc/supertonic)
- Tags: how-to-guide
- Published: 2026-06-13

---

**To report a bug in Supertonic, open a GitHub Issue in the supertone-inc/supertonic repository with a concise title, detailed environment information, and a minimal reproducible code example that demonstrates the failure in your specific language binding.**

Supertonic is a multi-language, on-device text-to-speech (TTS) system built on ONNX Runtime. The repository contains language-specific SDKs—including Python, Node.js, Java, C++, C#, Go, Swift, Rust, and Flutter—that share common helper implementations for loading ONNX models and executing inference pipelines. When you encounter unexpected behavior, following a structured reporting process helps maintainers reproduce and fix issues efficiently across all supported platforms.

## Preparing Your Bug Report

Before filing an issue, gather comprehensive context about your environment and the specific failure mode. This preparation reduces back-and-forth communication and accelerates the debugging process.

### Identify the Language Binding and Environment

Document the exact configuration where the bug occurs:

- **Language binding**: Specify which SDK you are using (e.g., Python, Node.js, C++, Rust).
- **System details**: Note your operating system, CPU architecture, and whether you are using GPU acceleration.
- **Runtime versions**: Include version numbers for Python (e.g., Python 3.12), ONNX Runtime (e.g., 1.16), and the Supertonic model version (e.g., Supertonic 3).
- **Source files**: Identify which files are exercised during the failure, such as [`py/example_onnx.py`](https://github.com/supertone-inc/supertonic/blob/main/py/example_onnx.py), [`cpp/example_onnx.cpp`](https://github.com/supertone-inc/supertonic/blob/main/cpp/example_onnx.cpp), or [`rust/src/example_onnx.rs`](https://github.com/supertone-inc/supertonic/blob/main/rust/src/example_onnx.rs).

### Create a Minimal Reproducible Example

Construct the smallest possible code snippet that triggers the bug. This example should be self-contained and runnable by maintainers without extensive setup. According to the source code analysis, providing a minimal example helps developers determine whether the issue lies in the shared helper modules or the language-specific wrappers.

## Filing the GitHub Issue

Once you have gathered the necessary information, submit your report through the official issue tracker.

### Navigate to the Issues Tracker

Open the Issues tab of the repository at `https://github.com/supertone-inc/supertonic/issues`. Click **New issue** and select the **Bug report** template if available; otherwise, choose **Open a blank issue**.

### Structure Your Bug Report

Format your issue using the following sections to ensure clarity:

- **Title**: Use a concise description, such as "Python SDK crashes on Windows when `lang='na'` is used".
- **Description**: Provide a brief summary of the problem.
- **Environment**: List your OS, architecture, language version, ONNX Runtime version, and model version.
- **Steps to Reproduce**: 
  1. Clone the repository (`git clone https://github.com/supertone-inc/supertonic.git`).
  2. Install dependencies for your language (see the Quick Start section in [`README.md`](https://github.com/supertone-inc/supertonic/blob/main/README.md)).
  3. Run the minimal code snippet provided below.
- **Expected Behavior**: Describe what you expected to happen.
- **Actual Behavior**: Include error messages, stack traces, or incorrect output.
- **Relevant Files**: Reference specific files like [`nodejs/example_onnx.js`](https://github.com/supertone-inc/supertonic/blob/main/nodejs/example_onnx.js) or [`cpp/helper.cpp`](https://github.com/supertone-inc/supertonic/blob/main/cpp/helper.cpp).
- **Additional Context**: Attach logs, screenshots, or core dumps for native crashes.

After reviewing your entry, click **Submit new issue**. The maintainers will label the report, request clarification if needed, and work toward a resolution.

## Understanding Supertonic's Architecture for Debugging

Supertonic's codebase is organized into two distinct layers. Understanding this architecture helps you pinpoint where bugs originate and communicate their location effectively to maintainers.

### Helper Implementations vs. Language Bindings

The architecture separates **model loading** (helper modules) from **language-specific entry points** (bindings):

- **Helper implementations**: These contain the core logic for ONNX model loading and inference. Key files include [`rust/src/helper.rs`](https://github.com/supertone-inc/supertonic/blob/main/rust/src/helper.rs) for the Rust implementation and [`cpp/helper.cpp`](https://github.com/supertone-inc/supertonic/blob/main/cpp/helper.cpp) for the C++ version.
- **Language bindings**: These are thin wrappers that call the helper code. Examples include [`py/example_onnx.py`](https://github.com/supertone-inc/supertonic/blob/main/py/example_onnx.py) for Python, [`nodejs/example_onnx.js`](https://github.com/supertone-inc/supertonic/blob/main/nodejs/example_onnx.js) for Node.js, and [`go/example_onnx.go`](https://github.com/supertone-inc/supertonic/blob/main/go/example_onnx.go) for Go.

When a bug surfaces, a minimal reproducible example allows maintainers to identify whether the problem exists in the shared helper code or within a specific language SDK. This distinction is critical because fixes in helper modules propagate to all language bindings, while binding-specific issues require targeted patches.

## Code Examples for Common Bug Scenarios

Include code snippets in your bug report that demonstrate the failure. Below are examples showing common error conditions that you can adapt to illustrate your specific issue.

### Python Example

This snippet from [`py/example_onnx.py`](https://github.com/supertone-inc/supertonic/blob/main/py/example_onnx.py) intentionally triggers a missing-model error by pointing to a nonexistent directory:

```python

# File: py/example_onnx.py

from supertonic import TTS

# Force a non-existent model directory to provoke an error.

tts = TTS(model_dir="nonexistent_path", auto_download=False)

try:
    wav, dur = tts.synthesize(
        text="Bug report test",
        lang="en",
        total_steps=8,
    )
except Exception as e:
    print("Caught error:", e)

```

### Node.js Example

This example from [`nodejs/example_onnx.js`](https://github.com/supertone-inc/supertonic/blob/main/nodejs/example_onnx.js) demonstrates an ONNX Runtime load failure:

```javascript
// File: nodejs/example_onnx.js
const { TTS } = require("./helper");

(async () => {
  // Point to an invalid model folder.
  const tts = new TTS({ modelDir: "invalid_dir", autoDownload: false });

  try {
    await tts.synthesize({
      text: "Node bug test",
      lang: "en",
    });
  } catch (err) {
    console.error("Error:", err.message);
  }
})();

```

### C++ Example

This snippet from [`cpp/example_onnx.cpp`](https://github.com/supertone-inc/supertonic/blob/main/cpp/example_onnx.cpp) triggers a missing-model assertion:

```cpp
// File: cpp/example_onnx.cpp
#include "helper.h"

int main() {
    try {
        // Intentionally use a wrong path.
        SupertonicHelper helper("does/not/exist");
        auto wav = helper.synthesize("C++ bug test", "en");
    } catch (const std::exception& e) {
        std::cerr << "Caught exception: " << e.what() << std::endl;
    }
    return 0;
}

```

When submitting your report, include the full console output and any stack traces generated by these examples.

## Summary

- **Report bugs via GitHub Issues** at the supertone-inc/supertonic repository to ensure maintainers can track and resolve them.
- **Include environment details** such as OS, architecture, language version, and ONNX Runtime version to facilitate reproduction.
- **Provide minimal reproducible examples** using the templates in [`py/example_onnx.py`](https://github.com/supertone-inc/supertonic/blob/main/py/example_onnx.py), [`nodejs/example_onnx.js`](https://github.com/supertone-inc/supertonic/blob/main/nodejs/example_onnx.js), or [`cpp/example_onnx.cpp`](https://github.com/supertone-inc/supertonic/blob/main/cpp/example_onnx.cpp).
- **Distinguish between helper and binding layers** to help maintainers identify whether the bug is in shared code ([`rust/src/helper.rs`](https://github.com/supertone-inc/supertonic/blob/main/rust/src/helper.rs), [`cpp/helper.cpp`](https://github.com/supertone-inc/supertonic/blob/main/cpp/helper.cpp)) or language-specific wrappers.
- **Attach logs and screenshots** when reporting crashes or visual glitches to provide complete diagnostic context.

## Frequently Asked Questions

### Where do I submit a bug report for Supertonic?

Submit all bug reports through the GitHub Issues tracker at `https://github.com/supertone-inc/supertonic/issues`. This centralized location allows the maintainers to triage, label, and track issues across all language bindings effectively.

### What information should I include when reporting a bug?

Include a descriptive title, your operating system and architecture, the specific language binding and versions (e.g., Python 3.12, ONNX Runtime 1.16), a minimal code snippet that reproduces the issue, and the complete error message or stack trace. Mentioning specific files like [`swift/ExampleONNX.swift`](https://github.com/supertone-inc/supertonic/blob/main/swift/ExampleONNX.swift) or [`csharp/ExampleONNX.cs`](https://github.com/supertone-inc/supertonic/blob/main/csharp/ExampleONNX.cs) helps maintainers locate the relevant code quickly.

### How do I know if the bug is in the helper code or the language binding?

If the same error occurs across multiple language SDKs when performing similar operations, the bug likely resides in the shared helper implementations ([`rust/src/helper.rs`](https://github.com/supertone-inc/supertonic/blob/main/rust/src/helper.rs) or [`cpp/helper.cpp`](https://github.com/supertone-inc/supertonic/blob/main/cpp/helper.cpp)). If the issue is isolated to one language and follows that language's specific error patterns, it is probably in the language binding wrapper (e.g., `flutter/lib/main.dart` for Flutter).

### Should I attach logs or screenshots to my bug report?

Yes, always attach full console output, stack traces, or screenshots when applicable. For native crashes, include core dumps or the complete terminal output. For UI issues in bindings like Flutter, screenshots demonstrate the visual defect that logs alone cannot capture.