Skip to content

Troubleshooting Themes

Jump to bottom
Bobby Comet edited this page Jul 31, 2026 · 3 revisions

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 include a standardized start.sh. Legacy drop-ins may lack it; import or rebuild, or add a launcher. Could also be a theme you downloaded with a similar file structure without a start.sh, in which case use import legacy theme. You did not change the project name. Leaving the template name makes the manager think it is an unfinished project, and if HUD is in the name, it is a similar story. This is to not confuse Conky Studio, as having multiple theme names with HUD makes it hard to target a specific theme.
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.

Clone this wiki locally