Troubleshooting

Troubleshooting

neotheme requires Neovim 0.12 or newer

Upgrade Neovim to 0.12 or newer. The version check runs whenever Neotheme applies a theme.

E185: Cannot find color scheme '...'

Built-in theme names are setup or session-selection values, not colorscheme entrypoints.

Correct:

require("neotheme").setup({ theme = "gruber-light" })
vim.cmd.colorscheme("neotheme")

Also correct for the current session:

:NeothemeSwitch gruber-light

Incorrect:

vim.cmd.colorscheme("gruber-light")

neotheme: unknown theme '...'

List the registered names with:

:NeothemeList

or:

print(vim.inspect(require("neotheme").themes()))

See Themes for the family inventory.

neotheme: unknown family '...'

Use a name returned by require("neotheme").families() or printed by :NeothemeList. Family names are lowercase, such as gruber, typeset, and understory.

The configured theme changed but the editor did not

setup() replaces configured state but does not change active highlights. Apply the baseline:

require("neotheme").setup({ theme = "gruber-lighter" })
require("neotheme").reset()

During startup, vim.cmd.colorscheme("neotheme") is the normal apply step.

A session switch disappeared after restart

This is expected. Browser acceptance, :NeothemeSwitch, and switch() are deliberately non-persistent. Put the preferred durable baseline in setup, or use :NeothemeReset to return to the configured theme during the current session.

The browser does not open

The browser requires Neotheme to be loaded first:

require("neotheme").setup()
vim.cmd.colorscheme("neotheme")

It also requires at least 64 columns and 18 usable rows.

The browser closes while resizing

Supported window sizes recalculate and re-center the selector, preview, and backdrop. If Neovim becomes smaller than 64 columns by 18 usable rows, Neotheme intentionally cancels the browser and restores its latest confirmed checkpoint rather than leaving clipped windows or a partial preview.

Reopen :Neotheme after enlarging the editor.

Escape or q kept a theme selected with Space

This is expected. Theme-row movement is preview-only, but Space confirms the selected theme and keeps the browser open. That confirmation becomes the new checkpoint, so <Esc> and q leave the editor on the most recently Space-confirmed theme. Before the first Space confirmation, they leave the editor on the browser-entry theme.

Lualine keeps the previous colors

Configure Lualine after Neotheme initially loads:

require("neotheme").setup({ theme = "gruber-light" })
vim.cmd.colorscheme("neotheme")

require("lualine").setup({
	options = { theme = "neotheme" },
})

Neotheme invalidates its Lualine theme modules whenever it applies a theme. If Lualine holds a separately resolved table, rerun Lualine setup after a browser or command switch. See Lualine.

Plugin highlights are missing

All plugin integrations default to disabled.

require("neotheme").setup({
	integrations = {
		telescope = true,
	},
})
vim.cmd.colorscheme("neotheme")

Confirm the key in Integrations and make sure the configured baseline was applied. Browser previews intentionally leave integration groups unchanged until Enter or Space confirms a theme.

configure_palette reports an unknown option or field

Only categories and fields listed in Palette Customization are accepted. Check spelling and nesting. For example:

palette.ui.accent = palette.syntax.keyword

A palette color is rejected

Supplied values must be strings in six-digit #RRGGBB form:

palette.ui.accent = "#e8c05b"

Short hex, named colors, and non-string values are rejected.

configure_palette must mutate its palette argument and return nil

Do not return a replacement table:

configure_palette = function(palette)
	palette.ui.accent = palette.syntax.keyword
end

The custom palette warning lists missing entries

theme = "custom" starts with empty category tables. Fill every role listed in Palette Customization to remove the warning. Partial custom palettes still load, but highlights that depend on missing values have no defined color.

A light custom palette leaves background set to dark

Custom themes default to background = "dark". Set the option after loading:

vim.cmd.colorscheme("neotheme")
vim.o.background = "light"

Built-in light themes set background automatically.

Colors are wrong in a terminal

Neotheme enables termguicolors and defines all 16 terminal colors. Confirm that the terminal emulator or GUI supports true color and that another plugin is not overwriting terminal globals after Neotheme applies a theme.

Help or quickfix has unexpected backgrounds

Neotheme applies sidebar window highlights to help and qf filetypes. Inspect winhighlight in the affected window if another plugin also manages those filetypes:

:setlocal winhighlight?

Report an issue

Include:

• Neovim version and editor dimensions
• :NeothemeCurrent output
• Configured setup options and enabled integrations
• Browser tab, selected family/theme, and close method when relevant
• Minimal reproduction steps
• Actual and expected behavior or highlight groups

Use the issue tracker.