Troubleshooting
Plugin Not Loading
Section titled “Plugin Not Loading”Symptom
Section titled “Symptom”Plugin doesn’t appear in evonic plugin list or doesn’t respond to events.
- Check that
plugin.jsonis valid JSON:cat plugins/my_plugin/plugin.json | python3 -m json.tool - Verify the plugin directory is in the correct location
- Run
evonic plugin reload my_pluginto force a reload - Check plugin logs:
evonic plugin logs my_plugin
Handler Not Being Called
Section titled “Handler Not Being Called”Symptom
Section titled “Symptom”Plugin loads but event handlers don’t execute.
- Ensure event names in
plugin.jsonmatch exactly (case-sensitive) - Verify handler function names follow the
on_<event_name>pattern - Check that the plugin is enabled:
evonic plugin enable my_plugin - Review logs for errors:
evonic plugin logs my_plugin --limit 50
Configuration Not Working
Section titled “Configuration Not Working”Symptom
Section titled “Symptom”Plugin config values aren’t being read or applied.
- Verify variable names in
plugin.jsonmatch exactly (case-sensitive) - Check config values:
evonic plugin config my_plugin - Set config values:
evonic plugin config my_plugin --set KEY value - Reload the plugin after changing config:
evonic plugin reload my_plugin
HTTP Requests Failing
Section titled “HTTP Requests Failing”Symptom
Section titled “Symptom”sdk.http_request() returns errors or times out.
- Check the URL is correct and accessible
- Increase timeout:
sdk.http_request(..., timeout=60) - Verify the external service is running and reachable
- Check logs for detailed error messages:
sdk.log(response.get('error'), level="error")
Permission Errors
Section titled “Permission Errors”Symptom
Section titled “Symptom”Plugin can’t read/write files or access certain resources.
- Ensure the Evonic process has read/write permissions to the plugins directory
- Check file permissions:
ls -la plugins/my_plugin/ - Run with appropriate user permissions
Common Error Messages
Section titled “Common Error Messages”"Plugin already exists"
Section titled “"Plugin already exists"”- Use
--forceflag to overwrite:evonic plugin install ./my_plugin.zip --force - Or uninstall first:
evonic plugin uninstall my_plugin
"Event handler not found"
Section titled “"Event handler not found"”- Verify handler function name matches event name:
on_<event_name> - Check for typos in
plugin.jsonevent names
"Invalid plugin.json"
Section titled “"Invalid plugin.json"”- Validate JSON syntax:
python3 -m json.tool plugin.json - Ensure all required fields are present:
id,name,version,description,events
"Module not found"
Section titled “"Module not found"”- Check that
handler.pyis in the plugin root directory - Verify there are no syntax errors in
handler.py:python3 -m py_compile handler.py