# How to Troubleshoot Common Supertonic Errors: A Complete SDK Guide

> Troubleshoot common Supertonic errors with this SDK guide. Diagnose invalid language codes, mismatched list sizes, missing ONNX models, and GPU issues across Python, Node.js, Go, and Web.

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

---

**Most Supertonic runtime errors stem from invalid language codes, mismatched input list sizes, missing ONNX model assets, or unsupported GPU configurations, all of which can be diagnosed by checking specific validation logic in the Python, Node.js, Go, and Web SDKs.**

Supertonic by supertone-inc is a multi-language, on-device text-to-speech (TTS) system built on ONNX Runtime that ships SDKs for Python, Node.js, Java, C++, C#, Go, Swift, Rust, and Flutter. When you troubleshoot common Supertonic errors, you are typically dealing with validation failures in the `UnicodeProcessor._preprocess_text` functions, tensor dimension mismatches, or missing model files referenced across language-specific helper modules. Understanding the exact source locations where these checks occur allows you to resolve issues quickly without guessing.

## Common Error Categories and Source Locations

### Language Validation Failures

The SDK validates every language code against an internal `AVAILABLE_LANGS` list before processing. You will encounter an `Invalid language: …` error when the supplied code is not recognized. In the Python SDK, this check occurs in [`py/helper.py`](https://github.com/supertone-inc/supertonic/blob/main/py/helper.py) at lines 102-104 within the `UnicodeProcessor._preprocess_text` method. Equivalent validation logic exists in Node.js at [`nodejs/helper.js`](https://github.com/supertone-inc/supertonic/blob/main/nodejs/helper.js) line 93, Go at [`go/helper.go`](https://github.com/supertone-inc/supertonic/blob/main/go/helper.go) line 861, and Rust at [`rust/src/helper.rs`](https://github.com/supertone-inc/supertonic/blob/main/rust/src/helper.rs) line 103. The complete list of valid codes is defined at [`py/helper.py`](https://github.com/supertone-inc/supertonic/blob/main/py/helper.py) line 13.

### Input Dimension Mismatches

The inference pipeline requires a strict 1-to-1 mapping between texts, style vectors, and language codes. When these lists differ in length, the SDK raises errors such as "Number of texts must match number of style vectors" or "Number of voice styles must match number of texts". This validation appears in Python at [`py/helper.py`](https://github.com/supertone-inc/supertonic/blob/main/py/helper.py) lines 185-188, Node.js at [`nodejs/helper.js`](https://github.com/supertone-inc/supertonic/blob/main/nodejs/helper.js) line 200, C++ at [`cpp/example_onnx.cpp`](https://github.com/supertone-inc/supertonic/blob/main/cpp/example_onnx.cpp) line 67, and Go at [`go/example_onnx.go`](https://github.com/supertone-inc/supertonic/blob/main/go/example_onnx.go) line 88.

### GPU Configuration Errors

If you attempt to enable GPU acceleration on a binary compiled without ONNX Runtime GPU libraries, you will receive `GPU mode is not supported yet`. This error is raised in Python at [`py/helper.py`](https://github.com/supertone-inc/supertonic/blob/main/py/helper.py) line 325, Go at [`go/helper.go`](https://github.com/supertone-inc/supertonic/blob/main/go/helper.go) line 861, and Swift at [`swift/Sources/Helper.swift`](https://github.com/supertone-inc/supertonic/blob/main/swift/Sources/Helper.swift) line 811. This typically occurs on platforms lacking GPU support or when the runtime was not linked against the CUDA libraries.

### Model Loading and Asset Failures

Errors like "Failed to load voice style file" or "Failed to initialize ONNX Runtime" indicate missing or corrupted model assets. The Web UI surfaces these at [`web/main.js`](https://github.com/supertone-inc/supertonic/blob/main/web/main.js) line 120, while Go reports them at [`go/helper.go`](https://github.com/supertone-inc/supertonic/blob/main/go/helper.go) line 944 and Python at [`py/helper.py`](https://github.com/supertone-inc/supertonic/blob/main/py/helper.py) line 944. These failures occur when the `assets` directory does not contain the required ONNX files or the [`unicode_indexer.json`](https://github.com/supertone-inc/supertonic/blob/main/unicode_indexer.json) manifest.

### Inference Runtime Errors

During synthesis, "Error during synthesis" or "Error during inference" typically signals malformed input tensors or runtime crashes. The Web SDK catches these at [`web/main.js`](https://github.com/supertone-inc/supertonic/blob/main/web/main.js) line 260, while the Go implementation reports them at [`go/example_onnx.go`](https://github.com/supertone-inc/supertonic/blob/main/go/example_onnx.go) line 147. These errors often result from passing `null` values or incorrectly shaped arrays into the inference session.

### File System and Permission Errors

Mobile and desktop applications may encounter "File no longer exists" or sandbox restrictions. In Flutter, this occurs at `flutter/lib/main.dart` line 185, while iOS reports similar issues at [`ios/ExampleiOSApp/TTSService.swift`](https://github.com/supertone-inc/supertonic/blob/main/ios/ExampleiOSApp/TTSService.swift) line 134. These errors happen when the SDK attempts to write temporary audio files to directories blocked by OS security policies.

## Step-by-Step Debugging Workflow

Follow this systematic approach to identify and resolve issues:

1. **Verify language codes** – Ensure your language string (e.g., `"en"`, `"ko"`, `"na"`) appears in the `AVAILABLE_LANGS` list at [`py/helper.py`](https://github.com/supertone-inc/supertonic/blob/main/py/helper.py) line 13. Avoid using full names like `"english"`.

2. **Check list parity** – Confirm that `len(texts) == len(langs) == len(styles)`. The SDK strictly enforces this 1-to-1 mapping across all language implementations.

3. **Validate runtime configuration** – For GPU usage, ensure you have installed `onnxruntime-gpu`. On macOS or CPU-only systems, explicitly disable GPU mode to avoid the error at [`py/helper.py`](https://github.com/supertone-inc/supertonic/blob/main/py/helper.py) line 325.

4. **Inspect model assets** – Verify that your `assets` folder contains all downloaded ONNX files and [`unicode_indexer.json`](https://github.com/supertone-inc/supertonic/blob/main/unicode_indexer.json) from Hugging Face. Missing files trigger the loading errors at [`web/main.js`](https://github.com/supertone-inc/supertonic/blob/main/web/main.js) line 120.

5. **Review console output** – Check `console.error` in Web, `logger.e` in Flutter, or stderr in Python/Go for the original exception text, which often includes the specific line number from the source files above.

6. **Enable verbose logging** – Set the environment variable `ORT_LOG_SEVERITY=VERBOSE` or use the `--debug` flag to surface ONNX Runtime internals and reveal low-level execution failures.

## Preventing Errors with Proper Implementation

### Validating Language Codes in Python

Always use short codes from the `AVAILABLE_LANGS` list to avoid the `ValueError` at [`py/helper.py`](https://github.com/supertone-inc/supertonic/blob/main/py/helper.py) lines 102-104.

```python
from supertonic import TTS

tts = TTS(auto_download=True)
voice = tts.get_voice_style(voice_name="M1")

# ✅ Correct: use "en" not "english"

wav, dur = tts.synthesize(
    text="Hello world!",
    lang="en",
    voice_style=voice,
    total_steps=8,
    speed=1.0,
)
tts.save_audio(wav, "out.wav")

```

### Ensuring List Parity in Node.js

Match the length of all input arrays to prevent the error at [`nodejs/helper.js`](https://github.com/supertone-inc/supertonic/blob/main/nodejs/helper.js) line 200.

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

const texts = ["Hola mundo!", "Bonjour le monde!"];
const styles = [await loadStyle("M1.onnx"), await loadStyle("F1.onnx")];
const langs = ["es", "fr"];  // Must match texts.length

const tts = new TTS({ autoDownload: true });
await tts.synthesize(texts, langs, styles);

```

### Configuring CPU-Only Mode in Go

Disable GPU on unsupported hardware to bypass the error at [`go/helper.go`](https://github.com/supertone-inc/supertonic/blob/main/go/helper.go) line 861.

```go
import "github.com/supertone-inc/supertonic/go"

func main() {
    cfg := supertonic.NewConfig()
    cfg.UseGPU = false  // Essential for Raspberry Pi and CPU-only systems
    
    tts, err := supertonic.NewTTS(cfg)
    if err != nil {
        log.Fatalf("Init error: %v", err)
    }
    // Proceed with inference...
}

```

### Handling Model Loading in Web Applications

Wrap initialization in try-catch blocks to handle the error at [`web/main.js`](https://github.com/supertone-inc/supertonic/blob/main/web/main.js) line 120 gracefully.

```javascript
async function init() {
  try {
    await loadModels();  // Fetches ONNX files
  } catch (e) {
    showError(`Error loading models: ${e.message}`);
    return;
  }
  // Continue with UI initialization
}

```

## Summary

- **Language validation** errors occur in [`py/helper.py`](https://github.com/supertone-inc/supertonic/blob/main/py/helper.py) at lines 102-104 when codes are not in `AVAILABLE_LANGS`.
- **List size mismatches** trigger errors at [`py/helper.py`](https://github.com/supertone-inc/supertonic/blob/main/py/helper.py) lines 185-188 and [`nodejs/helper.js`](https://github.com/supertone-inc/supertonic/blob/main/nodejs/helper.js) line 200 when texts, styles, and languages do not align 1-to-1.
- **GPU errors** at [`py/helper.py`](https://github.com/supertone-inc/supertonic/blob/main/py/helper.py) line 325 and [`go/helper.go`](https://github.com/supertone-inc/supertonic/blob/main/go/helper.go) line 861 indicate missing CUDA libraries or unsupported platforms.
- **Model loading** failures at [`web/main.js`](https://github.com/supertone-inc/supertonic/blob/main/web/main.js) line 120 and [`go/helper.go`](https://github.com/supertone-inc/supertonic/blob/main/go/helper.go) line 944 require verifying the `assets` directory contains all ONNX files and [`unicode_indexer.json`](https://github.com/supertone-inc/supertonic/blob/main/unicode_indexer.json).
- **File system** errors in Flutter and iOS stem from sandbox restrictions on temporary file access.

## Frequently Asked Questions

### Why do I get "Invalid language" error when using full language names?

The `UnicodeProcessor._preprocess_text` method in [`py/helper.py`](https://github.com/supertone-inc/supertonic/blob/main/py/helper.py) lines 102-104 and equivalent functions in other SDKs only accept standardized short codes like `"en"` or `"ko"`. Using full names like `"english"` causes immediate validation failures. Check the `AVAILABLE_LANGS` list at [`py/helper.py`](https://github.com/supertone-inc/supertonic/blob/main/py/helper.py) line 13 for the exact strings supported.

### How do I fix "Number of texts must match number of style vectors"?

This error originates at [`py/helper.py`](https://github.com/supertone-inc/supertonic/blob/main/py/helper.py) lines 185-188 and [`nodejs/helper.js`](https://github.com/supertone-inc/supertonic/blob/main/nodejs/helper.js) line 200 when the inference pipeline receives unequal list lengths. Ensure your texts, language codes, and style vectors arrays all have identical lengths before calling `synthesize()`. The SDK enforces this 1-to-1 mapping to maintain tensor alignment during batch processing.

### Can I use GPU acceleration on macOS or mobile devices?

GPU support depends on the specific ONNX Runtime binary compilation. Errors at [`py/helper.py`](https://github.com/supertone-inc/supertonic/blob/main/py/helper.py) line 325 and [`swift/Sources/Helper.swift`](https://github.com/supertone-inc/supertonic/blob/main/swift/Sources/Helper.swift) line 811 indicate the binary lacks GPU libraries. On macOS, you must use CPU-only mode (`UseGPU = false`), while mobile devices typically require specific builds with Metal or Vulkan backends. Install `onnxruntime-gpu` only on CUDA-capable Linux/Windows systems.

### What causes "Failed to load voice style file" errors?

This error at [`web/main.js`](https://github.com/supertone-inc/supertonic/blob/main/web/main.js) line 120 or [`go/helper.go`](https://github.com/supertone-inc/supertonic/blob/main/go/helper.go) line 944 occurs when the SDK cannot locate the ONNX model files or [`unicode_indexer.json`](https://github.com/supertone-inc/supertonic/blob/main/unicode_indexer.json) in the assets directory. Verify that you have downloaded all model files from Hugging Face and that your application has read permissions for the directory. The error often appears alongside network failures in web environments where the `fetch()` request for models fails.