If you’ve built a SAMSON Extension and it suddenly won’t load when you start SAMSON, you’re not alone. One of the most common issues developers and users stumble upon is version incompatibility between the Extension and the SAMSON SDK. It can be frustrating—especially when the code compiled just fine—but there’s actually a logic behind this behavior that’s easy to understand once you know the rules.
This blog post breaks down how version compatibility works in SAMSON, so you can avoid wasting time debugging issues that stem from mismatched SDK versions.
Understanding SAMSON’s Semantic Versioning
SAMSON and its Software Development Kit (SDK) follow semantic versioning: major.minor.patch. The important thing to understand is that Extensions are compatible with SAMSON only if certain version conditions are met:
- The major version number of the SAMSON SDK used to build the Extension must be identical to the major version number of SAMSON.
- The minor version number of the SDK must be less than or equal to the minor version number of SAMSON.
So for example:
- ✅ An Extension built with SDK 1.5.2 works with SAMSON 1.7.8
- ✅ An Extension built with SDK 1.3.5 works with SAMSON 1.7.8
- ❌ An Extension built with SDK 1.8.5 will not work with SAMSON 1.7.8
The reason: SDK 1.8.5 might require functions that 1.7.8 simply doesn’t have yet.
Why SAMSON Does This
This strict compatibility check is important to ensure Extensions aren’t loaded into an environment that lacks functionalities on which they depend. It helps prevent runtime errors and unexpected behavior.
When SAMSON starts, it automatically checks the SDK version tags of every Extension and compares them to its own version. If everything matches according to the rules above, the Extension is loaded. Otherwise, it’s skipped.
Can SAMSON Help With Updates?
Yes. When SAMSON has an Internet connection, it automatically updates Extensions to newer versions—as long as they are compatible with the current SAMSON version.
Say a user has SAMSON 1.7.8 and an Extension built with SDK 1.5.2. A newer version of this Extension is released and built with SDK 1.6.4. Since SAMSON 1.7.8 is still compatible with SDK 1.6.4, the upgrade happens automatically at startup.
However, if the new Extension was built using SDK 2.0.0, and the user is still running SAMSON 1.7.8, SAMSON will not load the upgraded Extension. It will keep using the last compatible version (in this case, the one built with SDK 1.6.4).
How Can You Avoid Issues?
- Check your SDK version before building a new release of your Extension.
- Encourage users to update SAMSON regularly through its built-in update functionality.
- Be transparent about version requirements when publishing your Extension.
Following these simple guidelines will help ensure a smoother experience for both Extension developers and users.
You can learn more in the official documentation.
SAMSON and all SAMSON Extensions are free for non-commercial use. You can download SAMSON at www.samson-connect.net.