mirror of
https://github.com/LukeHagar/volar-docs.git
synced 2025-12-06 04:22:01 +00:00
77 lines
2.8 KiB
Markdown
77 lines
2.8 KiB
Markdown
# Troubleshooting & FAQ
|
||
|
||
> [Docs Index](README.md) • [Repo README](../README.md) • [Error Handling](error-handling-and-resilience.md) • [Telemetry](telemetry-and-observability.md)
|
||
|
||
This FAQ aggregates the most common VolarJS issues reported by users, along with actionable fixes and references to relevant guides.
|
||
|
||
## Duplicate Diagnostics
|
||
|
||
**Symptom:** Same error appears twice (one from Volar, one from TypeScript).
|
||
|
||
**Fix:** Enable Take Over Mode or disable the built-in TypeScript server.
|
||
|
||
```json
|
||
{
|
||
"volar.takeOverMode.enabled": true,
|
||
"typescript.tsserver.enable": false
|
||
}
|
||
```
|
||
|
||
For Neovim/Sublime, ensure only Volar’s LSP client handles `.ts/.js` when Take Over Mode is on.
|
||
|
||
## “Cannot find module '@/…'”
|
||
|
||
1. Verify `tsconfig.json` includes `baseUrl` + `paths`.
|
||
2. Check `Output ▸ Volar` to confirm the intended `tsconfig` is loaded.
|
||
3. In monorepos, enable project references (`"composite": true`) or add each package tsconfig to the workspace.
|
||
|
||
## Schema Fetch Failures / Offline Mode
|
||
|
||
- Cache schemas locally (e.g., `~/.cache/volar-schemas`) or bundle them.
|
||
- Provide a configuration flag like `volarJsonYaml.schemas.allowRemote = false`.
|
||
- Log failures via `connection.console.warn` so users know which URI failed.
|
||
|
||
## Slow Diagnostics
|
||
|
||
Checklist:
|
||
|
||
1. Increase `VALIDATION_DELAY` (JSON/YAML example) to reduce frequency.
|
||
2. Disable unused services (Prettier, Emmet) if not required.
|
||
3. Profile with `VOLAR_TRACE=log` + `node --prof`; see [Performance & Debugging](performance-and-debugging.md).
|
||
4. Align TypeScript + Volar versions.
|
||
|
||
## Take Over Mode Not Activating
|
||
|
||
- Disable VS Code’s “TypeScript and JavaScript Language Features” extension.
|
||
- Set `volar.takeOverMode.enabled = true` and restart.
|
||
- Ensure `typescript.tsdk` points to the correct TS install if needed.
|
||
|
||
## Missing Hover/Completion in Monaco
|
||
|
||
- Confirm `@volar/monaco` worker bundle loads (check console).
|
||
- Ensure TypeScript is available inside the worker (`ts` global).
|
||
- Version-match server + worker bundles.
|
||
|
||
## Neovim “node: command not found”
|
||
|
||
- Install Node and set the `cmd` in `lspconfig` to `{ 'node', '/path/to/volar/server.js', '--stdio' }`.
|
||
- Consider bundling the server as an executable (`pkg`) for users without Node.
|
||
|
||
## CLI Always Succeeds
|
||
|
||
- Exit with code `1` when diagnostics include severity Error; see [CLI Integration](cli-integration.md).
|
||
- Provide `--max-warnings` if teams want warning thresholds.
|
||
|
||
## Log Locations
|
||
|
||
| Editor | Location |
|
||
| --- | --- |
|
||
| VS Code | Output ▸ Volar |
|
||
| Sublime | `View ▸ Show Console` |
|
||
| Neovim | Plugin-specific log file (`~/.cache/volar/log.txt`) |
|
||
| CLI | stdout/stderr (support `--log-file`) |
|
||
|
||
## Reporting Issues
|
||
|
||
Include editor/version, Node/TS/Volar versions, `tsconfig`, reproduction steps, and logs. Reference this FAQ so maintainers can triage quickly.
|