# Troubleshooting (/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 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.