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.