---
title: "Troubleshooting"
canonical: https://docs.qvac.tether.io/resources/troubleshooting/
collection: "Resources"
---

# Troubleshooting (/resources/troubleshooting)



## CLI error: command not found

### Situation

You ran a `qvac` command (e.g., `qvac doctor`) and the shell responded with:

```
zsh: command not found: qvac
```

(On bash: `bash: qvac: command not found`.)

### Cause

The `qvac` binary is shipped by the `@qvac/cli` npm package. It is only added to your shell `PATH` when `@qvac/cli` is installed globally. Without a global install, the binary is not discoverable by name from your shell.

### Solution

Install `@qvac/cli` globally:

```bash
npm install -g @qvac/cli
```

Then re-run your command. For example:

```bash
qvac doctor
```

<Callout type="success">
  **Tip:** If you cannot install the CLI globally, you can run it with `npx` instead:

  ```bash
  npx --package "@qvac/cli" qvac doctor
  ```
</Callout>

See [CLI → Usage](/cli#usage) for the full setup, including installing `@qvac/sdk` in your project.

## Startup failure: missing libatomic.so.1

### Situation

On a minimal Linux image, worker startup fails and the error cause includes:

```text
libatomic.so.1: cannot open shared object file: No such file or directory
```

The top-level SDK error may report an RPC initialization timeout. Check `error.cause` for the underlying loader error.

### Cause

The Linux `rocksdb-native` prebuilds used by the SDK's storage dependencies require `libatomic.so.1`. Minimal images such as `node:22-slim` may omit this library. The dependency is needed even for CPU-only inference, before a model is loaded.

### Solution

Install `libatomic1` in the Debian or Ubuntu environment that runs the worker:

```bash
sudo apt update
sudo apt install -y libatomic1
```

Omit `sudo` when running as root inside a container. Restart the application after installing the library. See [system requirements](/sdk/system-requirements#linux) and [issue #4290](https://github.com/tetherto/qvac/issues/4290).

## Startup crash: requested module does not provide a default export

### Situation

You ran `qvac bundle sdk`, started your app, and then the worklet crashed with:

<WrapCode>
  ```
  SyntaxError: The requested module '@qvac/sdk/tts-ggml/plugin' does not provide an export named 'default'
  ```
</WrapCode>

### Cause

This usually means there is version skew between `@qvac/cli` and `@qvac/sdk`.

An older CLI version may generate a bundle using outdated built-in plugin metadata, while a newer SDK version exports the renamed plugin only through its current named export shape. Starting with `@qvac/cli` 0.6.0, `qvac bundle sdk` delegates to `@qvac/sdk/commands`, which keeps the bundling logic aligned with the SDK.

### Solution

Upgrade `@qvac/cli`, then rebuild the SDK bundle:

```bash
npm install -g @qvac/cli@latest
qvac bundle sdk
```

If you do not install the CLI globally, run the latest version with `npx` instead.

## SDK fails to load on GCC-10-era embedded Linux

### Situation

You are running the QVAC SDK on a Yocto-based or other embedded Linux image with GCC 10 era `libstdc++` (GLIBCXX version 3.4.28 or lower). The SDK fails at module load time with an error such as:

<WrapCode>
  ```
  Error: /usr/lib/aarch64-linux-gnu/libstdc++.so.6: version `GLIBCXX_3.4.29' not found
  ```
</WrapCode>

### Cause

`rocksdb-native`, a transitive dependency reached through `corestore` and `hypercore-storage`, requires `GLIBCXX_3.4.30`. Its Linux ARM64 prebuilds are compiled against Ubuntu 22.04, and every version within the SDK's current semver range carries this floor. Pinning an older version does not help.

### Solution

Switch the embedded image toolchain from GCC to clang with static `libc++` linkage. This removes the versioned `libstdc++` symbol dependency entirely. The QVAC-owned inference addons (such as `@qvac/translation-nmtcpp`) already use this approach and carry no `libstdc++` requirement.

GCC-10-era embedded Linux images are not a currently supported target. See [GitHub issue #3365](https://github.com/tetherto/qvac/issues/3365) for the full diagnosis and audit.