Debugging

Common issues and fixes.

Connection problems

• Ensure Dot X is running before starting your plugin (the plugin server starts automatically with the app)
• The plugin server listens on http://127.0.0.1:3001 by default; override with DOTX_PLUGIN_PORT env var
• The SDK retries up to 5 times with a 2-second delay before giving up — watch the output for retry messages
• Check that waitForConnection() resolves (rarely needed; onLoad() already guarantees a live connection)
• Review app logs and plugin.log inside your plugin folder

Timeouts

• API calls fail after 30 seconds if the host doesn't respond
• Increase apiTimeout in the ConnectionConfig passed to runPlugin() if needed:

  runPlugin(MyPlugin, { apiTimeout: 60000 });

Manifest validation errors

• The runtime validates all required fields on startup; check the app logs or plugin output for a list of errors
• version must be valid semver (e.g. 1.0.0)
• dotxVersion must be a semver range (e.g. >=2.0.0)

Clean restarts

• Implement onUnload() to stop timers and close network handles
• Keep onUnload idempotent so rapid restarts don't leave stale state