How to Troubleshoot Common Supertonic Errors: A Complete SDK Guide

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 at lines 102-104 within the UnicodeProcessor._preprocess_text method. Equivalent validation logic exists in Node.js at nodejs/helper.js line 93, Go at go/helper.go line 861, and Rust at rust/src/helper.rs line 103. The complete list of valid codes is defined at 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 lines 185-188, Node.js at nodejs/helper.js line 200, C++ at cpp/example_onnx.cpp line 67, and Go at 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 line 325, Go at go/helper.go line 861, and Swift at 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 line 120, while Go reports them at go/helper.go line 944 and Python at py/helper.py line 944. These failures occur when the assets directory does not contain the required ONNX files or the 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 line 260, while the Go implementation reports them at 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 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 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 line 325.

4. Inspect model assets – Verify that your assets folder contains all downloaded ONNX files and unicode_indexer.json from Hugging Face. Missing files trigger the loading errors at 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 lines 102-104.

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 line 200.

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 line 861.

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 line 120 gracefully.

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 at lines 102-104 when codes are not in AVAILABLE_LANGS.
• List size mismatches trigger errors at py/helper.py lines 185-188 and nodejs/helper.js line 200 when texts, styles, and languages do not align 1-to-1.
• GPU errors at py/helper.py line 325 and go/helper.go line 861 indicate missing CUDA libraries or unsupported platforms.
• Model loading failures at web/main.js line 120 and go/helper.go line 944 require verifying the assets directory contains all ONNX files and 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 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 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 lines 185-188 and 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 line 325 and 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 line 120 or go/helper.go line 944 occurs when the SDK cannot locate the ONNX model files or 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}