# How to Troubleshoot ONNX Runtime Loading Errors in Supertonic

> Troubleshoot ONNX Runtime loading errors in Supertonic. Verify model files, check onnxruntime wheel compatibility, and ensure hardware execution provider match for smooth inference.

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

---

**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`](https://github.com/supertone-inc/supertonic/blob/main/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`](https://github.com/supertone-inc/supertonic/blob/main/py/helper.py) expects a directory containing exactly six files: four ONNX models and two JSON configuration files.

Check your assets folder:

```bash
ls <your-onnx-dir>

```

You should see:

- `duration_predictor.onnx`
- `text_encoder.onnx`
- `vector_estimator.onnx`
- `vocoder.onnx`
- [`tts.json`](https://github.com/supertone-inc/supertonic/blob/main/tts.json)
- [`unicode_indexer.json`](https://github.com/supertone-inc/supertonic/blob/main/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:

```python
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:

```bash
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:

```bash
pip install --upgrade --force-reinstall onnxruntime

```

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

```bash
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:

```bash
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`](https://github.com/supertone-inc/supertonic/blob/main/py/example_onnx.py) to test the full loading pipeline without your application code:

```bash
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:**

```python
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:**

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

```

**Validate model integrity (optional):**

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

```

## Summary

- **Supertonic** loads four ONNX models via `load_onnx_all` in [`py/helper.py`](https://github.com/supertone-inc/supertonic/blob/main/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`](https://github.com/supertone-inc/supertonic/blob/main/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`](https://github.com/supertone-inc/supertonic/blob/main/tts.json), [`unicode_indexer.json`](https://github.com/supertone-inc/supertonic/blob/main/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.