This page covers the most common issues encountered when running Vorto, grouped by symptom. Work through the relevant section top to bottom — each item adds one more thing to check before escalating further.Documentation Index
Fetch the complete documentation index at: https://docs.vorto-editor.dev/llms.txt
Use this file to discover all available pages before exploring further.
Syntax highlighting not working
Syntax highlighting not working
Vorto uses tree-sitter grammars for syntax highlighting. Grammars are not bundled with the binary — you must install them separately.Install the grammar for your languageFor example:Check which grammars are installedThe output shows each built-in recipe, whether the compiled library is present (If the compiler is missing, install it through your system package manager and then re-run
lib ✓ or lib ✗), and the status of the highlight queries.Ensure a C compiler is availableBuilding a grammar compiles a C source file. gcc or clang must be on your PATH:vorto grammar install.After installing a grammar, restart Vorto so it can load the newly compiled library.
LSP not starting
LSP not starting
Vorto starts LSP servers lazily — a server process only spawns when you open a file of the matching type. If features like diagnostics or hover are absent, work through these checks.Verify the server binary is installed and on PATHRun the server binary directly to confirm it’s reachable:If the command isn’t found, install the server (see Set up LSP support) and ensure its install location is in your
If the project lacks these files, the server may not start. Create the appropriate root file or add a custom This opens a status modal listing every language that has an LSP configured and whether the server is connected.
PATH.Check that root markers existVorto uses root marker files to locate the workspace root before starting a server. The built-in root markers are:| Server | Root markers |
|---|---|
| rust-analyzer | Cargo.toml, rust-project.json |
| pyright | pyproject.toml, setup.py, setup.cfg, requirements.txt |
| vtsls / typescript-language-server | package.json, tsconfig.json, jsconfig.json |
| gopls | go.mod, go.work |
| clangd | compile_commands.json, .clangd, Makefile, CMakeLists.txt |
root_markers override in your [lsp.<name>] config block.Check connection status with :lspFrom Command mode, run:Grammar install fails
Grammar install fails
Check the terminal output for build errorsGrammar installation prints detailed output to stderr. Look for compiler error messages immediately after the Install one through your system package manager if neither is found.Remove a broken install and retryIf a previous install attempt left a corrupt file behind, remove it and start fresh:Refresh only the query filesIf the library compiled correctly in the past but the highlight queries are stale, refresh them without rebuilding the grammar:
==> installing <name> line.Ensure a C compiler is presentPasted text has wrong indentation
Pasted text has wrong indentation
Vorto uses bracketed paste to receive clipboard content. In bracketed paste mode the editor receives the full paste as a single event rather than as a stream of individual key presses, which lets it suppress auto-indent during the paste. If your terminal does not support bracketed paste, each pasted newline triggers auto-indent and the result is over-indented.Check terminal supportBracketed paste is supported by most modern terminals (Kitty, iTerm2, Alacritty, WezTerm, Ghostty). If you’re using an older terminal emulator, upgrade or switch to one that supports it.Temporarily disable format-on-saveIf indentation is being mangled by the formatter running on save, you can disable it for the affected language in your config:Re-enable it once you’ve confirmed the paste looks correct.
Config file not loaded
Config file not loaded
Vorto looks for its config file in the following order, stopping at the first match:Check for TOML parse errorsSyntax errors in
.vorto/config.tomlin the current directory (workspace directory form).vortofile in the current directory (workspace single-file form)$XDG_CONFIG_HOME/vorto/config.toml~/.config/vorto/config.toml
config.toml are reported at startup in the terminal. If Vorto launches but your settings aren’t applied, look for a parse error message before the editor UI appears.Workspace config takes precedenceA .vorto file or .vorto/config.toml directory in the project root silently overrides the global config for that workspace. If settings change unexpectedly when you switch projects, check whether a workspace config exists:Key not working as expected
Key not working as expected
Vorto uses the Kitty keyboard protocol on terminals that support it, which allows unambiguous encoding of key combinations that traditional terminals conflate (e.g., Then inspect the log to see what key sequence Vorto actually received when you pressed the key in question:Compare the logged sequence with the binding you expect to be active and adjust your
Ctrl+Shift+letter, Alt+special). On terminals that don’t support the protocol, Vorto falls back to legacy encoding.Check terminal keyboard supportUse a terminal that supports the Kitty keyboard protocol (Kitty, Ghostty, WezTerm, and recent versions of Alacritty and iTerm2) to get the most reliable key handling. If you’re on a terminal that doesn’t support it, some modifier combinations may not be distinguishable.Log raw key events to diagnose mismatchesSet the VORTO_KEY_LOG environment variable to a file path before launching Vorto. Vorto will write every raw key event it receives to that file:[[bind]] entries in config.toml accordingly.