# 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.