Why Your SAMSON Extension Might Not Load—And How to Fix It

Molecular modelers and developers working with SAMSON often enhance their workflow with SAMSON Extensions. These Extensions, which may include everything from force field tools to file format importers, help extend the capabilities of the platform significantly. However, one issue that sometimes arises is that an Extension simply refuses to load at startup. If you’ve encountered this, you’re not alone—and there’s a good reason why it’s happening.

💡 The Core of the Problem

When you launch SAMSON, it attempts to load all installed SAMSON Extensions. However, it doesn’t just blindly load anything—it checks compatibility based on the version of the Software Development Kit (SDK) used to build the Extension versus the SDK version integrated into your current SAMSON installation.

SAMSON follows a semantic versioning system with three components:

  • major: Indicates a non-backwards-compatible update
  • minor: Adds functionality but remains backwards compatible
  • patch: Backwards-compatible bug fixes

What matters for Extension compatibility are the major and minor version numbers.

🧩 How Compatibility is Determined

At startup, SAMSON compares its own SDK version against the SDK version your Extension was built with. Here’s the compatibility rule:

  • The major version numbers must match.
  • The minor version number of the Extension’s SDK must be less than or equal to that of SAMSON.

Example: SAMSON version 1.7.8 (SDK 1.7.8)
✅ Can load Extension built with SDK 1.3.5 or 1.7.7
❌ Cannot load Extension built with SDK 1.8.5 (minor version too high)

🔄 Automatic Updates Make It Easier

If you’re connected to the Internet, SAMSON will automatically update Extensions to the latest compatible versions available on SAMSON Connect at startup. For example, if your current SAMSON version is 1.7.8 and the Extension is available in versions 1.5.2 and 1.6.4, SAMSON will automatically update to the 1.6.4 version at launch—without needing any intervention.

🚧 When Things Break

Problems arise when developers push a new version of their Extension using a newer major SDK version (e.g., 2.0.0), but you are still using an older SAMSON (e.g., 1.7.8). Since the major version number doesn’t match, SAMSON ensures your current compatible version of the Extension keeps running, but doesn’t update to the new one.

This safety net prevents runtime errors that would stem from using functions not yet supported in your installation. The downside? You won’t see the latest features or improvements unless you update SAMSON too.

✅ What You Can Do

  • Always keep SAMSON up to date to benefit from the latest compatible Extensions.
  • If an Extension fails to load, check the SDK version used during its build versus your SAMSON SDK version.
  • If you are developing Extensions, build them using the SDK version most widely adopted among your users—or communicate clearly what version users need.

Understanding how version compatibility works not only saves you time troubleshooting, but also helps ensure that your modeling environment stays as functional and stable as possible.

📖 Learn more in the full documentation.

SAMSON and all SAMSON Extensions are free for non-commercial use. You can get SAMSON at https://www.samson-connect.net.

Comments are closed.