Skip to main content

Troubleshooting Checklist

Debug from the boundary inward

First verify Stream Deck sees the plugin, then verify the manifest, then verify the process, then verify action events.

1. Plugin does not appear​

Check:

  • Stream Deck app is running.
  • Plugin directory ends with .sdPlugin.
  • Plugin is linked or installed.
  • manifest.json is valid JSON.
  • Plugin UUID is valid lowercase reverse-DNS.
  • Software.MinimumVersion is not higher than the installed Stream Deck app.
  • OS supports the current platform.
  • The Stream Deck app was restarted after installation.

Elgato notes that after a fresh install or app update, Stream Deck may run with elevated privileges and a restart can resolve plugins not showing.

2. Watch mode does not reload​

Check:

  • npm run watch is still running.
  • The generated watch script includes streamdeck restart <plugin_uuid>.
  • The UUID in the watch command matches the manifest UUID.
  • Rollup is rebuilding successfully.
  • Stream Deck is not blocked by OS permissions.
  • The changed file is under src/ or the watched manifest/plugin path.

Manual fallback:

npm run build
streamdeck restart com.example.plugin

3. Action appears but does nothing​

Check:

  • Action UUID in @action({ UUID: '...' }) matches the manifest action UUID.
  • The action class is imported by the plugin entry point.
  • The event method name matches the expected controller.
  • You are testing on a supported controller: key vs dial.
  • Errors are written to plugin logs.
  • Async calls are awaited and caught.

For quick isolation, replace external API work with:

await ev.action.setTitle('OK');

If that works, the issue is inside your integration logic, not Stream Deck event delivery.

4. Property inspector does not open​

Check:

  • PropertyInspectorPath points to an existing HTML file.
  • The path is relative to the *.sdPlugin directory.
  • The HTML does not depend on remote assets that fail offline.
  • Browser console errors are not blocking initialization.
  • Settings names in the inspector match action settings names.

Prefer local sdpi-components.js for reliable property inspector UI.

5. Settings are missing​

Check:

  • The action handles default values.
  • The property inspector writes the expected keys.
  • You did not rename a settings key without a compatibility fallback.
  • Multiple actions do not accidentally share incompatible settings shapes.

Use tolerant reads:

const mode = ev.payload.settings.mode ?? 'default';

6. Images do not show​

Check:

  • Image paths in the manifest are correct.
  • Files exist inside *.sdPlugin/imgs/.
  • File names match case exactly.
  • Images are packed, not ignored by .sdignore.
  • Runtime image generation writes outside immutable packaged files.

When setting images from code, ensure the image format and data URL are accepted by the SDK method you call.

7. Debugger cannot attach​

Check:

  • Nodejs.Debug is enabled in the manifest.
  • Stream Deck restarted after manifest changes.
  • You are attaching to the correct Node process.
  • A fixed debug port is not already in use.

Temporary fixed port:

{
  "Nodejs": {
    "Version": "24",
    "Debug": "--inspect=127.0.0.1:12345"
  }
}

8. Python cannot open the device​

Check:

  • The Stream Deck desktop app is not using the same device.
  • Linux HID permissions allow the current user to access the deck.
  • The device is physically connected and visible over USB.
  • You close the deck after crashes or restarts.
  • The target hardware model is supported by the Python library version.

Direct HID control and official Stream Deck app plugins are different operating modes. Avoid using both on the same hardware at the same time.

9. Pack fails​

Check:

  • streamdeck validate output first.
  • Required files exist in *.sdPlugin.
  • manifest.json references real files.
  • .sdignore is not excluding required assets.
  • Version and UUID fields are valid.
  • The plugin was built before packing.

10. Release regression checklist​

Before publishing:

  • Fresh install works.
  • Stream Deck restart works.
  • All actions can be added to a clean profile.
  • Property inspectors open and save settings.
  • Old settings still read correctly.
  • Offline mode does not break local UI.
  • Logs are useful but not noisy.
  • No private paths, secrets, or debug files are packaged.