Why Your SAMSON Extension May Not Load—and How to Fix It

It’s a familiar and often frustrating situation in molecular modeling platforms: you launch your software, expecting your favorite extension to be readily available—only to find it missing or non-functional. If you use SAMSON, there’s a good chance this is caused by a version mismatch between SAMSON and the SDK used to build the extension.

Understanding how SAMSON handles extension compatibility can help you avoid downtime, lost features, and confused debugging. Let’s walk through the reasoning behind this mechanism and how to ensure your extensions stay running smoothly.

Why version compatibility matters

SAMSON Extensions are compiled using the SAMSON SDK. At startup, SAMSON checks whether the SDK version used to build each installed extension is compatible with its own internal version. This isn’t arbitrary—extensions might rely on functions introduced in later versions of SAMSON, or behave unexpectedly if they access deprecated or altered APIs.

To guarantee stability, SAMSON applies these compatibility rules based on the semantic versioning system:

  • The major versions of SAMSON and the extension’s SDK must be equal. If one is 1.x.x and the other is 2.x.x, the extension won’t load.
  • The extension’s minor version must be less than the minor version of SAMSON. For example, SDK 1.5.2 is compatible with SAMSON 1.7.8, but SDK 1.8.5 is not.

By enforcing these rules, SAMSON prevents compatibility issues caused by progressive feature changes and ensures that only extensions built for older or equally mature environments are permitted to run.

Example scenario

Suppose your current SAMSON version is 1.7.8. An extension built with:

  • 1.5.2: ✅ Compatible
  • 1.7.7: ✅ Compatible
  • 1.8.5: ❌ Not compatible

In the third case, SAMSON refuses to load the extension, because it may rely on features that don’t exist yet in version 1.7.8.

What you can do

To avoid problems:

  • Keep SAMSON up-to-date: As long as you stay within the same major version, newer releases will maintain compatibility with extensions built with earlier SDK minor versions.
  • Know your SDK version: If you’re developing extensions, confirm the SDK version you’re using aligns with your target SAMSON version.
  • Let SAMSON auto-update your extensions: When a compatible extension update becomes available on SAMSON Connect, SAMSON will upgrade it automatically at startup.

When extensions won’t update

Let’s say you’re still using SAMSON 1.7.8, and a developer releases a new version of their extension built with SDK 2.0.0. SAMSON will not update the extension because its new version would be incompatible. You’ll remain on the last compatible release (e.g., 1.6.4).

This behavior ensures you won’t get a broken extension, but it also means that to benefit from newer versions, you may need to update SAMSON itself.

Knowing how versioning works can prevent unnecessary troubleshooting and give you more control over your modeling setup. If you ever feel unsure about compatibility or updates, you can learn more in the SAMSON documentation.

SAMSON and all SAMSON Extensions are free for non-commercial use. You can download SAMSON here.

Comments are closed.