How to Troubleshoot ONNX Runtime Loading Errors in Supertonic

To fix ONNX Runtime loading errors in Supertonic, verify your model directory contains all four required ONNX files, ensure you're using the correct onnxruntime wheel for your platform, and check that the execution provider matches your hardware capabilities.

Supertonic loads its text-to-speech inference graphs using ONNX Runtime inside py/helper.py. The loading pipeline relies on three core helper functions that instantiate inference sessions for the TTS model stack. When any step fails, the library raises specific exceptions that point to missing files, incompatible execution providers, or corrupted runtime installations.

Verify the ONNX Model Directory Structure

The load_text_to_speech function in py/helper.py expects a directory containing exactly six files: four ONNX models and two JSON configuration files.

Check your assets folder:

ls <your-onnx-dir>

You should see:

• duration_predictor.onnx
• text_encoder.onnx
• vector_estimator.onnx
• vocoder.onnx
• tts.json
• unicode_indexer.json

If any file is missing or misnamed, load_onnx (line 283) raises a FileNotFoundError when attempting to create the InferenceSession. Fix this by re-downloading the assets from the official release or copying them from the repository's assets/onnx/ folder.

Check Execution Provider Configuration

Supertonic defaults to CPU inference only. Inside load_text_to_speech (line 322), the code explicitly raises a NotImplementedError if you attempt GPU mode:

if use_gpu:
    raise NotImplementedError("GPU mode is not fully tested")
else:
    providers = ["CPUExecutionProvider"]

Common provider errors occur when:

• CPU path: You installed onnxruntime-gpu but are running on a CPU-only machine, causing InvalidArgument: Unable to find provider CPUExecutionProvider.
• GPU path: You manually overrode the provider to ["CUDAExecutionProvider"] but lack matching CUDA drivers.

Fix: Install the standard CPU wheel with pip install onnxruntime. If you must use GPU, install onnxruntime-gpu and ensure your CUDA runtime versions match the compiled binaries.

Validate ONNX Runtime Installation

Confirm your installation before loading models:

python -c "import onnxruntime as ort; print(ort.__version__)"

Versions older than 1.12 may cause cryptic DLL load errors or unsupported operator failures. Reinstall if needed:

pip install --upgrade --force-reinstall onnxruntime

On Linux, missing system libraries (libgomp, libstdc++) surface as OrtError: Failed to load library. Install them via:

apt-get install libgomp1

Debug Common Runtime Errors

When load_onnx fails at line 283, examine the traceback to identify the specific failure mode:

InvalidArgument errors indicate an unsupported operator set in the ONNX model. This happens when the model was exported with a newer opset than your runtime supports. Solution: Upgrade ONNX Runtime to ≥ 1.12 or regenerate the model with an older opset.

OrtError with library loading failures suggest a missing shared library (libonnxruntime.so on Linux or .dll on Windows). Solution: Verify platform compatibility (many-linux vs. many-linux2014) and check dependencies:

ldd $(python -c "import onnxruntime, os; print(os.path.join(os.path.dirname(onnxruntime.__file__), 'libonnxruntime.so'))")

Run the Minimal Example for Isolation

Use py/example_onnx.py to test the full loading pipeline without your application code:

python py/example_onnx.py \
  --onnx-dir ./assets/onnx

If this script prints Using CPU for inference and proceeds to synthesis, your environment is correctly configured. If it aborts early, the error points directly to the failing step—either a missing model file or a provider mismatch.

Diagnostic Snippets for Debugging

Add these checks before calling load_text_to_speech to isolate issues:

Verify file existence:

import os
from pathlib import Path

def verify_assets(onnx_dir: str):
    required = [
        "duration_predictor.onnx",
        "text_encoder.onnx", 
        "vector_estimator.onnx",
        "vocoder.onnx",
        "tts.json",
        "unicode_indexer.json"
    ]
    missing = [f for f in required if not os.path.exists(os.path.join(onnx_dir, f))]
    if missing:
        raise FileNotFoundError(f"Missing ONNX assets: {missing}")
    print("All assets verified")

Check available providers:

import onnxruntime as ort
print("Available providers:", ort.get_available_providers())

Validate model integrity (optional):

import onnx
onnx.checker.check_model("path/to/model.onnx")

Summary

• Supertonic loads four ONNX models via load_onnx_all in py/helper.py to initialize the TTS pipeline.
• Missing files in the assets directory raise immediate FileNotFoundError exceptions before inference begins.
• Execution provider mismatches occur when using GPU wheels on CPU-only machines or vice versa; Supertonic officially supports CPUExecutionProvider only.
• Installation issues manifest as OrtError or library loading failures, often fixed by reinstalling onnxruntime>=1.12 or installing missing Linux system libraries.
• Isolation using py/example_onnx.py definitively determines whether errors stem from your code or the environment.

Frequently Asked Questions

Why does Supertonic raise "GPU mode is not fully tested"?

Supertonic explicitly disables GPU execution in load_text_to_speech by raising a NotImplementedError when use_gpu=True. This prevents unsupported configurations because the repository only validates CPU inference paths. If you need GPU acceleration, you must manually modify the providers list to ["CUDAExecutionProvider"] and install onnxruntime-gpu, but this configuration is not officially supported.

How do I fix "Unable to find provider CPUExecutionProvider"?

This error occurs when you installed onnxruntime-gpu (which excludes CPU providers) but are running on a machine without CUDA. Uninstall the GPU package and install the CPU-only version: pip uninstall onnxruntime-gpu && pip install onnxruntime. Verify the fix by running python -c "import onnxruntime as ort; print(ort.get_available_providers())" and confirming CPUExecutionProvider appears in the list.

What causes "Failed to load library libonnxruntime.so" on Linux?

This OrtError indicates missing system dependencies or a platform mismatch. The onnxruntime wheel requires libgomp1 and compatible glibc versions. Install missing libraries with apt-get install libgomp1, then verify library linkage using ldd on the shared object file inside your Python packages directory. If dependencies show "not found," reinstall the wheel after ensuring your distribution matches the wheel's many-linux tag.

Where should I place the ONNX model files?

The load_text_to_speech function expects an absolute or relative path to a directory containing the four model files (duration_predictor.onnx, text_encoder.onnx, vector_estimator.onnx, vocoder.onnx) plus configuration JSONs (tts.json, unicode_indexer.json). Pass this path as the onnx_dir argument. The repository provides reference assets in the assets/onnx/ folder that you can copy directly to your working directory.

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