Skip to content

Conversation

@aryamohanan
Copy link
Contributor

@aryamohanan aryamohanan commented Nov 14, 2025

BREAKING CHANGE

  • Dropped support for --experimental-loader
  • Dropped support for esm-loader.mjs file

Notes:

--experimental-loader is already not working for Node versions >= v18.19.0 (documented already)
esm-loader.mjs works with --experimental-loader only.
We are dropping support for < v18.19.

Reference

Node.js Version Loader Command Tracing Behavior Before(v5) Tracing Behavior After(v5) Notes
18.18 --experimental-loader ./node_modules/@instana/collector/esm-loader.mjs ✅ Worked ❌ No longer works 18.18 support dropped in v5.
18.18 --import ./node_modules/@instana/collector/esm-register.mjs ❌ Already didn’t work ❌ Still doesn’t work register api not available in earlier versions
18.19+ --experimental-loader ./node_modules/@instana/collector/esm-loader.mjs ❌ Already didn’t work ❌ Still doesn’t work ESM off-thread; early tracer exit with error log in v5.
18.19+ --import ./node_modules/@instana/collector/esm-register.mjs ✅ Works ✅ Works Recommended approach for Node ≥18.19; ensures ESM tracing.
18.19+ autotrace set to module_v1 ❌ Already didn’t work ❌ Still doesn’t work ESM off-thread; early tracer exit with error log in v5.

Autotrace webhook: https://github.ibm.com/instana/autotrace-mutating-webhook/pull/670

if (esmUtil.hasExperimentalLoaderFlag()) {
// eslint-disable-next-line no-console
console.error(
'Node.js introduced breaking changes in versions 18.19.0 and above, leading to the discontinuation of support ' +
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion:

introduced breaking changes

IMO this is too much information without a link to their breaking change.

Thats why IMO:

For Node.js versions later than 18.19, the --experimental-loader flag and ESM support are no longer available.


// This loader worked with '--experimental-loader' in Node.js versions below 18.19.
// TODO: Remove 'esm-loader.mjs' file and this log in the next major release (v6).
if (esmUtil.hasEsmLoaderFile()) {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The use case here is:

--import esm-loader.mjs

Right?

Its very nice to catch the wrong usage - especially because we drop the syntax.

I feel like the error message is not on point?

@kirrg001
Copy link
Contributor

We need a todo to cleanup task for internal Github usages of "--experimental-loader".

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

v5 v5 release items

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants