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

Molecular modelers who extend SAMSON with custom tools and scripts often face a frustrating situation: an extension that worked yesterday suddenly refuses to load after an update. This issue typically stems from version incompatibilities between SAMSON and the Software Development Kit (SDK) used to build the extension. Understanding how versioning works in SAMSON can help you avoid disruptions—and even design more sustainable extensions.

The Root of the Problem

When SAMSON launches, it performs a compatibility check for each installed extension. Behind the scenes, SAMSON compares its own internal version number (structured as major.minor.patch) with that of the SDK used to build the extension. SAMSON will only load the extension if:

  • The major version of SAMSON and the SDK match exactly
  • The minor version of SAMSON is greater than or equal to the SDK’s minor version

If either of these rules is violated, SAMSON skips loading the extension—often without fanfare, leading to user confusion.

Examples That Make It Clear

Let’s say you developed an extension with SDK version 1.5.2, and you’re running SAMSON version 1.7.8. Good news: SAMSON will load your extension. 🧪

However, if your extension was built with SDK version 1.8.5 and your SAMSON version is still 1.7.8, you’re in trouble. The minor version of the SDK (8) is higher than that of SAMSON (7), meaning your extension might call functionality SAMSON doesn’t support yet. In that case, SAMSON simply won’t load the extension.

How to Avoid Extension Downtime

  • Build with an older SDK if you want to ensure compatibility with a broad range of users who may not have updated SAMSON recently.
  • Update SAMSON regularly. Extensions built with slightly newer SDKs won’t work unless your SAMSON version keeps up.
  • Test your extensions with the lowest SAMSON version you intend to support.

What About Auto-Updates?

If SAMSON is connected to the Internet, it will automatically update extensions—but only if those extensions are built with a compatible SDK version. For example, if your installed SAMSON is 1.7.8 and the extension’s newest version was built with SDK 1.6.4, you’ll get the update. If it’s been built with SDK 2.0.0, you won’t.

Managing Expectations: Extension Versioning

Each extension can also specify its own version (major.minor.patch), but this is just for user information and is not used by SAMSON to determine compatibility. The only version that matters for loading is that of the SDK.

How This Helps You

By understanding version compatibility in SAMSON, you can:

  • Avoid debugging frustration
  • Make build and update decisions more confidently
  • Ensure a smoother experience for those who use your tools

To learn more about how SAMSON manages versions and compatibility, visit the official documentation: https://documentation.samson-connect.net/users/latest/versioning/

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

Comments are closed.