Troubleshooting

401 Unauthorized

Check:

• The Authorization header is present
• The header uses Bearer <token>
• You are using an external API key for /v1/*
• The key was not revoked

No local speech model is active

If dictation or /v1/audio/transcriptions fails before transcription starts:

• Open Settings -> Local speech models
• Download a built-in model such as Whisper Base, Whisper Small, or SenseVoice, or place a compatible Whisper.cpp .bin file in the models directory
• Activate the model you want the host to use

This applies only when Settings -> Routing and models -> STT mode is set to Local.

A settings change does not seem to take effect

Settings now save automatically after each change.

If a dictation priority, provider, or routing change does not seem to apply:

• Wait until the settings footer switches back from Saving...
• Reopen Settings and confirm the new value is still selected
• Retry dictation after the auto-save completes

Cloud STT is selected but transcription still fails

Check:

• Settings -> Routing and models -> STT mode is set to Cloud
• A valid cloud STT provider is selected
• The provider profile is enabled
• The provider API key is configured
• The cloud STT model name is valid for that provider

Prompt Lab Smart Clean returns the original text

This is often expected.

Smart Clean in Prompt Lab uses only local cleanup rules. It does not call the selected provider, model, preset, or prompt override. If the input has no low-risk fillers, repetitions, or obvious self-repairs, the result may stay unchanged and the run may show Local rules · <1ms.

Prompt Lab Polished says Add the API key for groq in Settings first

This means the provider request was not allowed to start because the configured transform provider is missing an API key.

Check:

• Settings -> Provider profiles contains a valid API key for the selected provider
• The provider profile is enabled
• The chosen model exists for that provider

Then reopen Prompt Lab or rerun the comparison.

Prompt override seems ignored in Prompt Lab

Prompt overrides apply only to Polished.

If you paste a prompt override into a Smart Clean variant, it will not be used because Smart Clean is intentionally local-only in V1.

whisper-rs-sys build failure

If npm run dev or cargo check fails while compiling whisper-rs-sys on Windows:

• Try npm run cargo:check first because it auto-detects common Windows libclang locations
• Make sure a 64-bit libclang.dll is available on the machine
• Set LIBCLANG_PATH to the directory that contains that DLL
• Retry the build after reopening the shell if needed

This is a build prerequisite for the local Whisper runtime, not a runtime API configuration issue.

ONNX Runtime or SenseVoice startup failure on Windows

If the desktop app fails while preparing the built-in SenseVoice runtime:

• Start the app through the repository scripts such as npm run dev, npm run build, or npm run cargo:check
• Avoid launching cargo directly from a shell that skips scripts/with-libclang.mjs
• Retry after deleting a partial ONNX Runtime download only if the script reports a corrupted archive

The repository startup scripts now download and wire up the required Windows ONNX Runtime files automatically.

macOS global shortcuts do not trigger

Check:

• System Settings -> Privacy & Security -> Accessibility includes the terminal, Codex host, or packaged VILab app you are launching
• You are testing on a recent build that includes the macOS event-listener shortcut backend
• The shortcut contains either Command or Control
• The shortcut does not conflict with obvious system-reserved combinations such as Cmd+Space or Cmd+Option+Space

The current default macOS shortcut is Cmd+Shift+Option+D.

macOS dictation finishes but the recording animation looks flat

If text still transcribes correctly, the microphone input is usually reaching the model.

Check:

• The app has microphone permission
• You are running version 0.1.6 or later, which boosts the macOS recording level used by the overlay animation
• You are testing from the latest npm run dev session or a rebuilt packaged app

This symptom usually indicates a UI level-mapping issue, not a transcription failure.

The Windows release app exits during startup

If the packaged desktop app opens and immediately exits on Windows:

• Open %APPDATA%\\com.vilab.desktop\\startup-trace.log
• Create an issue at GitHub Issues
• Attach startup-trace.log and include the Windows version, the installer version, and whether the crash happens on first launch

If %APPDATA%\\com.vilab.desktop\\startup-trace.log is empty or missing, mention that in the issue as well.

Service unreachable

Check:

• The desktop app is running
• The configured Server URL is correct
• The host firewall allows inbound traffic on the service port
• The client is calling the reachable LAN IP or hostname

LAN clients cannot connect

Check:

• The host is not still bound only to 127.0.0.1
• The client and host are on the same network
• The service port is not blocked by security software

Wrong model error

/v1/audio/transcriptions accepts only:

• The current public STT model alias returned by /health

If you send any other model value, the service returns 400 Unsupported model.

Unsupported audio format

The current local HTTP transcription endpoint accepts WAV audio in this phase.

If you send another container or codec, convert it to WAV before calling /v1/audio/transcriptions.