Blog
An SDK Compatibility Matrix Developers Can Trust
Publish the runtime, OS, and API versions you test. A matrix you do not run is a promise. When a cell fails in the wild, the error should name the cell.
2026-09-28 · 6 min read · AethelLayer
Test what you print
If the README says Node 18, 20, and 22, CI should install on those three. If it says macOS and Linux, a Windows failure should be labeled unsupported or it should be in CI. Silent support is how you collect bugs you cannot reproduce.
Put the matrix in one table at the top of the install doc. A paragraph of 'we support modern environments' is not a matrix.
The error should name the cell
Print the runtime, the OS, and the SDK version inside the unsupported-engine error. Then the developer can see they are off the matrix without opening a browser.
Use a stable code for 'unsupported runtime' and a different code for 'runtime we claim to support but this call failed'. The second one is your bug.
Drop a cell in public
When you stop testing a version, say so in a minor release before you reject it. The rejection error links to that note. A sudden engines bump is a break, even if the API did not change.
Probes from a dropped version should fall, not spike, after the release. If they spike, the announcement did not land in the error.
Do not expand the matrix from one anecdote
One laptop on an old glibc is not a new supported platform. A cluster of the same OS and the same code is. Read the probes before you add a row you will have to maintain.
The matrix is a promise to fix the cells inside it. Everything outside gets a clear no.
Keep reading
Capture the failure before they leave
Capture the failure before they leave. Book early access or talk to sales, then install @aethellayer/sdk when you are onboarded.