Troubleshooting Themes

Troubleshooting Themes

Problems that show up in Manager, on the desktop after Start, or when sharing a built folder.

Theme appears in Manager but will not start

Check	Detail
start.sh present and executable	Studio builds an included standardized start.sh. Legacy or downloaded themes may not. Import or rebuild if needed. Rename all projects before building; leaving names like HUD can make Manager matching ambiguous when multiple unfinished/default themes exist. Use something like test instead, if unfinished.
Working directory	Start from the theme folder so relative lua_load / script paths resolve
Conky on PATH	Same as Troubleshooting
Lock / single-instance	Previous instance still running; Stop in Manager or clear a stale lock if your start.sh uses one
Permission	chmod +x start.sh if you copied the folder by hand

Blank or empty desktop HUD

1. Confirm the process is running (Manager status / pgrep conky).
2. Alignment + gaps may place the window off the visible screen — reset Canvas alignment (e.g. top_left) and small gaps.
3. Canvas size may be tiny or huge relative to the monitor.
4. Visibility: Layers eye-toggle hides visuals from codegen.
5. Sources may return empty (wrong iface, no battery, weather not cached yet).
6. Own / double-buffer / compositor quirks — try another window_type on the Canvas node if available (normal / desktop / dock / auto).
7. GNOME Wayland: see Troubleshooting.

Wrong data or stuck values

Symptom	Try
Network always zero	Set the correct interface on the source node; rebuild
GPU empty	Vendor tools / permissions; check Hardware report
Weather empty	Script needs network; allow a few poll intervals; check script errors in logs
Music empty	Install playerctl; start a supported player

After Build & Install, old theme still shows

• You may have started a different folder with a similar name
• Rebuild after graph changes; Manager runs files on disk, not the unsaved Studio buffer
• Save the project JSON separately if you need the graph later

Paths and assets

Symptom	Try
Missing images	Files not in images/ or path still absolute to another machine
Custom script fails	Script not copied into scripts/; missing +x; interpreter not installed
Font fallback	Font not installed on the target system

When sharing, prefer the built folder for “just run it,” and fix paths before zip. See Sharing Projects.

Imported legacy themes

• Expect Custom Lua blobs for complex drawing
• Re-attach images image/media import is limited (Legacy Import)
• Run preview, then Build so start.sh is Studio-standard

theme.json / README

Editing metadata in Manager does not start Conky by itself. A valid runtime still needs conf + Lua + start.sh. Generate theme.json for listings and humans; fix runtime files if Start fails.

Nuclear options

1. Build to a fresh folder name.
2. Run ./start.sh in a terminal and read stderr.
3. Minimal test: one Text visual with a constant string; if that fails, the issue is session/Conky, not your graph.
4. X11 session test if Wayland is ambiguous.