volar-docs/docs/troubleshooting-faq.md

Troubleshooting & FAQ

Docs Index • Repo README • Error Handling • Telemetry

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.

{
  "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.
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.
• 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.