Shady Headstash

  2. Docs
    3. Troubleshooting

Troubleshooting

Shader Engine prefers visible errors over silent failure, so when something’s wrong it usually tells you where to look — most often in the Status parameter or as a notification in the browser window. Here’s how to read the common ones.

Shader Engine doesn’t appear in Resolume

  • Restart Resolume. It only scans the plugin folder on launch.
  • Check the folder. Confirm the plugin file is in the exact folder Resolume lists under Preferences → Video (the sources & effects / plugin folders). Custom folder? Install there.
  • Right OS build. Make sure you installed the Windows build on Windows / macOS build on macOS.
  • macOS Gatekeeper. If the bundle is blocked, right-click → Open, or clear quarantine: 
    xattr -dr com.apple.quarantine "~/Documents/Resolume Arena/Extra Effects/ShaderEngineEffect.bundle"
  • Resolume version. Shader Engine needs Resolume 7.4+.

See Installing the Plugin for the full install walkthrough.

A shader won’t compile

You’ll see an error in Status (in Resolume) and as a toast in the browser/editor.

  • Read the message. It’s written for shader authors and names the problem; if you’re editing, check the line it references.
  • The composition is safe. A failed compile never crashes Resolume — it keeps rendering the last good shader.
  • Try a known-good shader (e.g. a simple ISF generator) to confirm the plugin itself is healthy, then come back to the problem shader.
  • If it’s an import, the source shader may use features that didn’t translate — see below.

A Shadertoy import failed or looks wrong

Not every Shadertoy shader maps cleanly to ISF. Common causes:

  • Multi-buffer / feedback shaders (multiple Shadertoy “Buffer” tabs) — these often don’t translate fully.
  • Channel inputs — shaders that sample specific textures, cubemaps, sound, or the keyboard.

What to do:

  • Shader Engine won’t present a broken import as a success — if it reports a translation failure, believe it.
  • Many near-misses can be finished by hand in the editor.
  • Try a different shader — single-pass Shadertoy shaders have the best hit rate.

Search or download fails (remote API errors)

  • It’s non-fatal. Discovery is separate from playback — a failed search never disrupts your composition, and anything already in your library keeps working.
  • Retry. Upstream services occasionally rate-limit or hiccup; the hosted proxy smooths most of this over and can fall back to the public Shadertoy API.
  • Check connectivity. Importing needs a network connection; performing does not.
  • Providers/keys. Under Preferences → Shadertoy / ISF you can change the provider or add your own Shadertoy API key.

A shader is “missing” or won’t load from the library

  • File moved or renamed? The library is just files on disk — if you moved a shader in Finder/Explorer, its old path won’t resolve. Re-load it from its new location.
  • Composition points at an old path. Compositions store the Shader Path. If you reorganized your library after saving, re-select the shader via Browse Library or the Shader Path picker.
  • Wrong library folder. Confirm Preferences → Library points at the folder your shaders are actually in.
  • Unsupported file. Shader Engine loads .isf, .fs, .frag, .glsl, and .json (plus .milk in the Source variant).

Nothing renders, but there’s no error

  • Is a shader loaded? A fresh Shader Engine instance is empty until you load one.
  • Is Rate at 0? Rate = 0 pauses time — a time-based shader will look frozen. Nudge it positive.
  • Effect vs. Source. The Effect needs something beneath it to process; if the layer below is empty, there may be nothing to show. Use the Source variant for standalone generators.
  • Resolution/opacity. Standard Resolume checks — layer opacity, blend mode, bypass.

Getting more detail

Preferences → Log and Preferences → Debug expose runtime logs, which are useful when reporting a bug or diagnosing a stubborn shader.

Still stuck?

Note the shader (or Shadertoy URL), the exact error text from Status or the log, your OS, and your Resolume version — that’s everything needed to get you unblocked quickly.