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:

npm install -g @qvac/cli

Then re-run your command. For example:

qvac doctor

npx --package "@qvac/cli" qvac doctor

See CLI → Usage for the full setup, including installing @qvac/sdk in your project.

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:

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

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:

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:

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

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 for the full diagnosis and audit.