A saved change does not appear
Section titled “A saved change does not appear”Check the selected theme and category. Preview affects only the window containing the editor. Importing a package does not select it. Editing the source folder used for import does not edit the installed copy; use Open theme folder on the catalogue entry.
For terminal colors or fonts, check Settings > Terminal for personal overrides. Those values take precedence over the theme. For a fixed light or dark theme, changing the System/Light/Dark preference does not override appearance in the manifest.
Use Refresh after external file edits. The application also refreshes selected theme resources through native events, filesystem watches and window focus.
The editor rejects the document
Section titled “The editor rejects the document”| Error or symptom | Fix |
|---|---|
| Unknown field | Check the version 2 format. Arbitrary top-level fields are not allowed. |
| Duplicate key | Keep one occurrence of each JSON object key. |
| Invalid color | Use the supported structured color forms or put other CSS expressions in a stylesheet. |
| Missing asset | Verify the relative path and include the file in the installed package. |
| Theme changed on disk | Copy the draft before reloading the externally changed file, then reconcile the edits. |
| Read only | Duplicate a plugin-owned theme before editing it. |
| Icon/color field conflict | Keep iconTheme in a separate package without color surfaces. |
A failed validation or save keeps the draft. Resource failures keep the last working appearance; they do not prove that the newly selected theme was applied successfully.
Import a version 1 theme
Section titled “Import a version 1 theme”Older packages use theme.json with version: 1. Import converts supported data to version 2 theme.jsonc and preserves the original file. Editing an already installed legacy theme writes theme.jsonc on its first save.
Unsupported legacy data produces an error rather than being silently dropped. Keep the original package until the converted theme has been checked in both appearances. Existing theme-selection and appearance preferences remain in theme-settings.json.
Recover from unreadable CSS
Section titled “Recover from unreadable CSS”Start the application in safe mode, open Settings > Themes and select DeepMono plus built-in file and interface icons. Close the application and launch it normally.
Both --safe-mode and --disable-plugins skip third-party code and custom themes. The legacy environment variable LOMI_SAFE_THEME=1 skips custom themes only.
Safe startup does not delete the broken files. Back them up and fix the package before selecting it again. CSS can hide controls, so recovery should not depend on finding a button inside the broken theme.
Removing a package-owned theme
Section titled “Removing a package-owned theme”A theme contributed by a plugin belongs to that plugin’s immutable package. Duplicate it if you want a separate editable copy. Before uninstalling its owner, switch any selected color, file-icon or interface-icon theme from that package to a fallback.
Diagnose by symptom
Section titled “Diagnose by symptom”| Symptom | Check |
|---|---|
| The new entry is missing | Category, search, source and status filters; use Clear filters. |
| Save is disabled | The draft may be unchanged, invalid, busy or read-only. |
| Preview worked but the terminal did not change | Preview is local to Settings; save and select, then inspect terminal overrides. |
| A value returns after deleting it | Check common, the matching variant, imported data, CSS and personal terminal settings. |
Color validation rejects rgb(...), a color name or var(--x, ...) |
Use the structured color subset; a stylesheet supports broader CSS. |
| Font name has no effect | A family name does not install a font. Check @font-face, paths, bundled assets and user overrides. |
| An interface icon is blank | Check its font’s actual character map, fontId and the font load error. |
| Some controls retain their old icon | Unmapped or missing IDs fall back to built-ins. Plugin-drawn icons are separate. |
| Light icon associations do not win | Compare specificity; a base filename rule can outrank a light default. |
| Import fails despite a small manifest | Check CSS, asset, total size, entry count and path limits as well. |
| A native file is rejected as a VS Code document | Use Import folder for the native theme.jsonc package. |
| VSIX export fails | Use a writable output folder and a new filename/location; existing exports are not overwritten. |
Diagnose a source conflict without losing edits
Section titled “Diagnose a source conflict without losing edits”Copy the raw draft to a separate file first. Close the editor, refresh the library and reopen the installed theme. Compare the externally saved version with your copy, then reapply the intended changes and save. Do not delete the newer file to silence the revision check.
Remove a standalone local copy
Section titled “Remove a standalone local copy”Select a working replacement first in every relevant category. Open the library using Open folder, back up the local theme folder and move it outside the library. Use Refresh. There is no theme-card delete button. Package-owned themes are managed through their plugin, not by manually changing its immutable package.
Source: theme editor, migration and storage, safe-startup flags.