Shady Headstash

  2. Docs
  3. Shader Engine Docs
    4. 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.
  • Wrong extension for the browser. The LOCAL tab lists ISF shaders by the .fs extension (and Shadertoy exports by .json). An ISF file named .isf, .frag, or .glsl won’t appear in the list — rename it to .fs, or load it directly via Shader Path / Ctrl+O.
  • Unsupported file. The Shader Path picker loads .fs, .isf, .frag, .glsl, and .json.

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.