Troubleshooting

Typical problems and ways to fix them.

📑 Table of Contents

Installation
Extras
Colorschemes
Performance
Keymaps
LSP
macOS
Getting Help

📦 Installation

lazyvimx extras aren’t visible in :LazyExtras

Check the boot module import:

{ "lazyvimx/nvim", name = "lazyvimx", import = "lazyvimx.boot" }

Check whether the extras source is registered (there should be an entry with the 󰬟 icon):
```
:lua vim.print(require("lazyvim.util.extras").sources)
```
vim
Restart Neovim and update the plugins: :Lazy update.

Plugins won’t install

Check the version: :version — Neovim >= 0.10.0 is required
Look at the log: :Lazy log
As a last resort — reinstall the plugins from scratch:
```
rm -rf ~/.local/share/nvim/lazy
nvim
```
bash

setup() options are ignored

Options must land in the "lazyvimx" plugin spec (the opts field) or an explicit require("lazyvimx").setup() call

Check the merge result:

:lua vim.print(require("lazyvimx").config)

🧩 Extras

An extra is enabled but doesn’t work

Restart Neovim — extras apply on startup
Check the dependencies. Some extras require others:
- git.gitlab → ui.diff-view
- dap.vscode-js → the LazyVim dap.core extra
- test.jest → the LazyVim test.core extra
- ui.better-progressbar → the Ghostty terminal
Look at the warnings: :messages (search for “Missing extra”)

Check that the extra is actually loaded:

:lua print(require("lazyvimx.util.general").has_extra("ui.winbar"))

Buffer groups don’t appear

The add-groups override is needed (part of core.overrides):
```
{ import = "lazyvimx.extras.core.overrides" }
```
lua

Check the config:

:lua vim.print(require("lazyvimx").config.bufferline_groups)

Test the pattern on the current file:

:lua print(vim.fn.expand("%"):match("%.tsx$"))

symbol-usage counters aren’t showing

The LSP must be running: :LspInfo
The ui.symbol-usage extra is enabled: :LazyExtras
In insert mode the counters are hidden on purpose (ui.better-insert-mode)
Restart the LSP: :LspRestart

🎨 Colorschemes

The theme doesn’t follow the system

Is the override on? You need core.overrides (or specifically overrides.lazyvim.auto-switch-colorscheme-on-signal)
Switching fires on the Signal autocmd — the Neovim process must receive a signal from an external OS-theme watcher (see Configuration)

Check the theme detection:

:lua print(require("lazyvimx.util.general").theme_is_dark())

A manual check:

:lua vim.api.nvim_exec_autocmds("Signal", {})

The wrong theme variant gets picked

Look at the households:

:lua vim.print(require("lazyvimx").config.colorscheme_households)

What the variant selection returns:

:lua print(require("lazyvimx.util.general").get_flavor())

If perf.restore-last-colorscheme is enabled — the last used variant gets restored; switch the theme manually and the choice will be remembered

A custom colorscheme doesn’t apply

The theme must be installed as a plugin (lazy = false, priority = 1000)
The household is added to colorscheme_households, and variant names start with the household name
lazyvimx custom highlights don’t extend to third-party themes

⚡ Performance

Slow startup

Profile:

nvim --startuptime startup.log
sort -nk2 startup.log | tail -20

and :Lazy profile

Enable fewer extras: core.overrides + targeted imports instead of core.all

High memory usage

{ import = "lazyvimx.extras.perf.stop-inactive-lsp" } — stopping inactive LSPs
{ import = "lazyvimx.extras.buf.delete-inactive" } — closing old buffers

A laggy interface

Snacks animations are already off via the disable-animation override (part of core.overrides)
Try turning off the heavier UI extras: ui.scrollbar, ui.symbol-usage, ui.highlighted-colors
Check the terminal itself — rendering speed varies a lot

⌨️ Keymaps

lazyvimx keymaps don’t work

Is core.keys enabled?

{ import = "lazyvimx.extras.core.keys" }

Keymaps are bound to plugins: no plugin (the extra is off) — no keymap. See the “Requires” column in Keybindings
Who took the key:
```
:verbose map <leader>cr
```
vim
Leader is space: :echo mapleader

The Russian layout doesn’t work

Is the extra enabled?

{ import = "lazyvimx.extras.motions.langmapper" }

Restart Neovim after enabling it
Check the mapping of a specific key:
```
:verbose map ц
```
vim

A keymap conflict

Disable the lazyvimx keymap in your config:

return {
	{
		"LazyVim/LazyVim",
		keys = {
			{ "<leader>cr", false },
		},
	},
}

🧠 LSP

The LSP won’t start

:LspInfo — client status
:Mason — is the server installed
:LspLog — the error log

Diagnostics aren’t displayed

With the ui.better-diagnostic extra the native virtual text is off — diagnostics show at the cursor as a single line
Check the configuration:
```
:lua vim.print(vim.diagnostic.config())
```
vim

No LSP or autoformat on an sshfs mount

That’s by design: the buf.remote-mounts extra disables the LSP, autoformat, swap, and undo for buffers under ~/mnt — for speed and to keep file permissions intact. Not what you want — disable the extra.

🍎 macOS

The system theme isn’t detected

Check the command:
```
defaults read -g AppleInterfaceStyle
```
bash
In dark mode it returns “Dark”, in light mode — an error (that’s normal)

Check from Neovim:

:lua print(require("lazyvimx.util.general").theme_is_dark())

Files skip the trash

Install the trash utility:

brew install trash

Without it neo-tree deletes files the regular way.

Chezmoi sync doesn’t fire

Is the binary installed? which chezmoi
The sync fires on the LazyUpdate event — that is, after :Lazy update

The override is part of core.overrides; individually:

{ import = "lazyvimx.overrides.lazyvim.auto-apply-chezmoi-on-lazy-update" }

🆘 Getting Help

In an issue include:

the Neovim version (:version) and the OS

reproduction steps on a minimal config:

local lazy_opts = {
	spec = {
		{ "lazyvimx/nvim", name = "lazyvimx", import = "lazyvimx.boot" },
		{ import = "lazyvimx.extras.core.all" },
	},
}

error messages: :Lazy log, :messages

🐞 Debugging

" Spec modules
:lua vim.print(require("lazy.core.config").spec.modules)

" The lazyvimx config
:lua vim.print(require("lazyvimx").config)

" Profiling
:Lazy profile

" Integration autocmds
:autocmd Signal
:autocmd User LazyUpdate