Skip to main content
RunBook Academy

← All break/fix scenarios in OPNsense

advancedServices~25 min

Break/Fix: Plugin Upgrade Breaks Functionality

Reported symptoms

  • ●Plugin-related GUI tabs are missing or empty
  • ●Plugin service fails to start after an upgrade
  • ●System log shows a PHP or template error referencing the plugin

Evidence

  • · Firmware → Plugins lists the plugin as "out of date" but reinstalling fails
  • · system log: "cannot redeclare class <PluginName>" or template not found
  • · /var/log/<plugin>.log or /usr/local/etc/<plugin>/ shows parse errors
Diagnosis and resolutionclick to reveal

Root cause

The plugin was upgraded to a version that depends on a newer OPNsense core, or the upgrade replaced a template/script that no longer matches the existing config. A common cause is upgrading a plugin across an OPNsense major version without first upgrading the core.

Remediation

1. Identify the plugin and its current version: pkg info | grep <plugin>. 2. Check the plugin's changelog or release page for compatibility with your OPNsense version. 3. Either downgrade the plugin to a compatible version, or upgrade the OPNsense core to a compatible version. 4. Reinstall the plugin from Firmware → Plugins and verify the GUI tabs and service come back.

Verification

Plugin GUI tabs render; plugin service starts; integration points (DNS, IPsec, Suricata) work as expected.

Prevention

Treat plugin upgrades as part of the upgrade plan: do not upgrade plugins across major OPNsense versions unless the plugin changelog explicitly supports the new core. Read the plugin's release notes before applying. Test in lab.

Scenario

You are operating an OPNsense edge and have just upgraded a plugin. The following symptoms appear:

  • Plugin-related GUI tabs are missing or empty
  • Plugin service fails to start after an upgrade
  • System log shows a PHP or template error referencing the plugin

Available evidence:

  • Firmware → Plugins lists the plugin as “out of date” but reinstalling fails
  • system log: “cannot redeclare class <PluginName>” or template not found
  • /var/log/<plugin>.log or /usr/local/etc/<plugin>/ shows parse errors

Your task

Determine the cause, recover, document, and validate.

Investigation

The investigation follows the discipline taught in Part XLIV:

  1. Form hypothesis, find evidence, test, validate.
  2. Use the available evidence above to bound the search.
  3. Reach one of the likely root causes.

Recovery procedure

(Do not reveal until you have reasoned through the problem.)

  1. Identify the failing component.
  2. Apply the remediation pathway.
  3. Validate with the verification step.
  4. Document the incident.

Remediation

  1. Identify the plugin and its current version: pkg info | grep <plugin>. 2. Check the plugin’s changelog or release page for compatibility with your OPNsense version. 3. Either downgrade the plugin to a compatible version, or upgrade the OPNsense core to a compatible version. 4. Reinstall the plugin from Firmware → Plugins and verify the GUI tabs and service come back.

Verification

Plugin GUI tabs render; plugin service starts; integration points (DNS, IPsec, Suricata) work as expected.

Rollback

Remove the plugin (pkg delete <plugin>) if needed; expect the integration to be lost until reinstalled correctly.

Prevention

Treat plugin upgrades as part of the upgrade plan: do not upgrade plugins across major OPNsense versions unless the plugin changelog explicitly supports the new core. Read the plugin’s release notes before applying. Test in lab.