Troubleshooting OpenMod Plugin Load Failures

[- Alex - 36]

Troubleshooting OpenMod Plugin Load Failures
A Repeatable Diagnostic Workflow
GGU Public Technical Knowledge Base

Public Knowledge Base:
This article is written for both GGU administrators and the wider server-hosting community. General instructions are platform-neutral where possible; GGU-specific practices are identified separately.

 

Applies To

• OpenMod server operators

 

Prerequisites

• Console/log access
• Plugin package/version information

 

What You’ll Accomplish

Determine why an OpenMod plugin did not load and recover without random changes.

 

Symptoms of a Load Failure

• Plugin commands do not exist.
• Configuration never appears.
• Console reports package/dependency errors.
• Plugin starts and immediately fails.
• Reload produces an exception.
• Another plugin reports a missing service/library.

 

Diagnostic Order

1. Confirm the plugin file/package is actually installed.
2. Confirm the plugin targets the correct game/platform.
3. Confirm dependencies are installed.
4. Check the first load exception.
5. Validate YAML/configuration.
6. Confirm the plugin version is compatible with its dependencies.
7. Temporarily return to the last known-good version if the failure began after an update.

 

Dependency Problems

Package-based plugins may rely on other packages. A missing or incompatible dependency can prevent a plugin from loading even when the plugin DLL itself is present.

 

Configuration Problems

A plugin can fail because a required configuration value is malformed, missing, or no longer valid after an update. Compare the current config against the plugin's current defaults/release documentation.

 

Rollback

A rollback is not simply replacing the DLL. If the new version changed persisted data or configuration format, determine whether the previous version can safely read the newer data before downgrading.

 

GGU Implementation Notes

For GGU in-house plugins, compare the deployed build against the Gitea release/commit used by the server. Production should not depend on an untracked local DLL with no reproducible source revision.

 

Upstream References

• OpenMod Plugins
• OpenMod Logging
• OpenMod Configuration Files

 

Golden Gamers United — Public Technical Knowledge Base
General guidance first. GGU implementation details second.