Why Your SAMSON Extension Might Not Load (and How to Fix It)

Have you ever built a useful SAMSON Extension, only to find it doesn’t load when you or others start SAMSON? If you’re a molecular modeler depending on custom tools or collaborating with developers who build SAMSON Extensions, this scenario might already sound familiar.

Fortunately, there’s a clear logic behind this behavior. Understanding the SDK version compatibility system used by SAMSON can save you time and headaches—and this post will walk you through it.

What’s Actually Happening at Startup

When SAMSON starts, it checks each extension’s build version and compares it to its own version. If the SDK version used to build the extension isn’t compatible with the installed SAMSON version, the extension simply won’t load. Why? To prevent crashes or unexpected behavior caused by functions that may not be available.

The Rule of Compatibility

The compatibility is based on semantic versioning and follows a consistent set of rules:

  • The major version of the SDK used to build the extension must match SAMSON’s major version.
  • The minor version of the SDK must be smaller than SAMSON’s own minor version.

This means SAMSON will load SDKs from the same major version era that are older in minor version—but not those from future releases. For instance:

  • SDK 1.5.2 ➝ ✅ Compatible with SAMSON 1.7.8
  • SDK 1.8.5 ➝ ❌ Incompatible with SAMSON 1.7.8

What About Automatic Updates?

If your SAMSON is connected to the internet and sees a newer, compatible version of an Extension on SAMSON Connect, it will automatically update it at startup. This only happens if the new version meets the same compatibility criteria. Otherwise, your current version will remain unchanged and functional.

So, sticking to an older version of SAMSON might prevent access to newer Extensions—even if updates are available. Keeping SAMSON up to date ensures maximum compatibility with the growing ecosystem of Extensions on SAMSON Connect.

Version Conflicts in Practice

Imagine your project relies on an extension developed with SDK version 1.6.4. If you’re running SAMSON version 1.5.8, it won’t load because it might not have the features the extension calls. Now imagine you upgrade SAMSON to 1.7.8—you’re back in action.

This compatibility model helps maintain platform stability across scientific projects where reproducibility—and avoiding computation errors—matters.

Best Practices for Molecular Modelers

  • Check the SDK version your Extensions were built with, especially when downloading from external sources.
  • Keep SAMSON updated to ensure support for the widest range of Extensions.
  • Collaborate with extension developers to ensure they build compatible versions for the community.

To learn more about how SAMSON handles version compatibility, visit the official documentation:

SAMSON Versioning Documentation

SAMSON and all SAMSON Extensions are free for non-commercial use. You can download SAMSON at www.samson-connect.net.

Comments are closed.