instrumentation.server.js can evaluate app modules before Server.init() when the bundler colocates a shared dependency ($env/dynamic/private silently undefined)

[SobolievOleksii]

Describe the bug

With kit.experimental.instrumentation.server: true and adapter-node, src/instrumentation.server.ts is documented as being loaded before any application code. However, its build output is not isolated from the application's chunk graph: if the instrumentation file imports an npm package that application code also imports, the bundler may colocate that package into a chunk that also contains application modules. The compiled instrumentation entry then imports that chunk — evaluating application modules before Server.init() has called set_private_env().

Any application module that reads $env/dynamic/private at module scope then silently captures undefined for every env value. There is no error at startup — things fail later at request time in whatever way the stale values produce.

This is a nastier variant of #14286: there the env modules are imported by instrumentation.server.ts itself; here instrumentation never touches $env — it merely dynamically imports @opentelemetry/api, and the chunking pulls in unrelated app modules.

Concretely, our instrumentation.server.ts begins with:

const { context, propagation, trace } = await import('@opentelemetry/api');

@opentelemetry/api is also imported by our hooks.server.ts and API-client wrapper modules (which read $env/dynamic/private at module scope to configure base URLs). In the production build the bundler placed @opentelemetry/api inside the same chunk as those app modules, so the compiled build/instrumentation.server.js starts with:

import('./server/chunks/chunks/better-auth.js-DA2TiEpY.js') // ← this is `await import('@opentelemetry/api')`

Instrumenting the chunks confirms the evaluation order at process start:

EVAL app chunk (module-scope createClient reads env)   ← first thing the process does
captured API_BASE_URL = undefined
SET_PRIVATE_ENV called (real values)                   ← too late

Every outgoing fetch in the app then failed instantly with TypeError: Failed to parse URL from /v1/... (baseUrl undefined), taking down the whole login flow in our deployed environment.

The failure is platform/heuristic-dependent, which makes it very hard to catch: building the same commit with the same lockfile on Windows produced a layout where @opentelemetry/api got its own chunk cluster (propagation-api/trace-api/diag) with no app code — that build works fine. The Linux CI build produced the broken colocation. So it works on every dev machine and breaks only in the deployed artifact.

Reproduction

Mechanism summary (a minimal repo needs the bundler to pick the colocating layout, which is heuristic-dependent — I can invest in a pinned repro if that helps triage):

1. svelte.config.js: kit.experimental.instrumentation.server: true, adapter-node.
2. src/instrumentation.server.ts: top-level await import('some-shared-pkg') (e.g. @opentelemetry/api).
3. hooks.server.ts (or anything in its import graph) also imports some-shared-pkg, and some server module in that graph reads $env/dynamic/private at module scope.
4. Build with vite 8 (rolldown). If the bundler colocates some-shared-pkg with the app modules (observed on ubuntu-latest, not on Windows, same inputs), the compiled build/instrumentation.server.js dynamic-imports the app chunk before start.js runs, and the module-scope env reads see {}.

Verification that Server.init() itself is fine: in the compiled output it correctly calls set_private_env() before get_hooks() — the problem is purely that instrumentation's import graph can reach app chunks earlier than init.

Logs

TypeError: Failed to parse URL from /v1/authenticate/mitId
    at new Request (node:internal/deps/undici/undici:12302:19)
    at request (file:///app/build/server/chunks/chunks/better-auth.js-DA2TiEpY.js:47061:14)

System Info

@sveltejs/kit: 2.69.2
@sveltejs/adapter-node: 5.5.7
@sveltejs/vite-plugin-svelte: 7.2.0
vite: 8.1.3 (rolldown)
node: 26.3.0
broken build: GitHub Actions ubuntu-latest
working build (same commit + lockfile): Windows 11

Severity

serious, but I can work around it

Workaround: never read $env/dynamic/private at module scope — we now wrap every module-scope singleton that reads env in a Proxy-based lazy() helper that defers creation to first property access. But the failure mode is silent, platform-dependent, and contradicts the mental model that instrumentation.server.ts merely runs "before" the app — it can cause app code to run before the server is initialized.

Additional Information

Possible directions:

• Build instrumentation.server.ts as an isolated graph (duplicate shared deps instead of sharing chunks with the app), so importing a package from instrumentation can never evaluate app modules.
• Or have the adapter entry call set_private_env()/set_public_env() (from process.env) before importing instrumentation.server.js, so early-evaluated app modules at least see real values.
• At minimum, document that any package imported from instrumentation.server.ts that is also used by app code may drag app modules into pre-init evaluation.

[elliott-with-the-longest-name-on-github]

@SobolievOleksii do you have @opentelemetry/api in devDependencies or dependencies? adapter-node should be externalizing everything in dependencies so having it in a shared chunk shouldn't even be possible

[elliott-with-the-longest-name-on-github]

Working on a PR stack to deal with some of this... in the first place, @opentelemetry/api should never end up bundled -- it should always be externalized. It requires a single instance of itself (otherwise it won't work). I expect the reason you're seeing this behavior is because you have it in devDependencies instead of dependencies.

One thing we can do is force it into external dependencies in adapter-node and kit core.

The other thing I'm toying with is whether we can make dynamic environment variables work with it. It'd require initializing them prior to the instrumentation file running, which should be fine. The only way it could shoot you in the foot is if somehow $app/env imports code that you need to instrument, which seems... far-fetched?

[SobolievOleksii]

@elliott-with-the-longest-name-on-github Neither — that turned out to be the missing piece, thanks for the pointer. @opentelemetry/api is not in our dependencies at all: it's a transitive dependency (peer of @opentelemetry/sdk-node & co., which are in dependencies). adapter-node's externalization is Object.keys(pkg.dependencies), so a hoisted transitive package doesn't match and gets bundled — and from there the colocation with app chunks can happen.

Minimal reproduction: https://github.com/SobolievOleksii/kit-16288-repro (~7 files: instrumentation does await import('@opentelemetry/api'), hooks + an env-reading app module import the same package).

CI run demonstrating it on ubuntu-latest: https://github.com/SobolievOleksii/kit-16288-repro/actions/runs/29054915614 — the compiled build/instrumentation.server.js resolves the import to the app chunk:

compiled instrumentation.server.js dynamic imports: [ "'./server/chunks/chunks/api-client.js-UJKdGIT2.js'" ]
[instrumentation] start
[api-client] module evaluated; env.MY_BASE_URL = undefined   ← app module, before Server.init()
[instrumentation] imported @opentelemetry/api: object
{ captured: null, live: 'https://api.example' }

The same commit built on Windows resolves the import to a standalone chunk and works — the layout is platform-dependent, so it's invisible on dev machines and only breaks in the CI-built artifact.

Adding @opentelemetry/api to dependencies is a valid workaround for this specific package (we'll do that). But the class of problem survives externalization: any local shared module ($lib/...) imported from instrumentation.server.ts has the same effect, and transitive deps are easy to miss. So the ask stands: either build instrumentation as an isolated graph, or set env before importing it, or document the constraint.

[elliott-with-the-longest-name-on-github]

Can you share your use case? This isn't really a quirk of SvelteKit so much as it is just how tracing works. Your dependencies that you import into tracing setup code need to be externalized. Are there certain dependencies you need in both your instrumentation setup and in your app code but can't externalize?

[SobolievOleksii]

Thanks for turning this around so quickly — two PRs within the hour is more than we hoped for. 🙏

To answer the use-case question properly: it's the textbook OTel split, nothing exotic. instrumentation.server.ts boots the SDK (NodeSDK + auto-instrumentations + OTLP exporters), and — as its very first statement — grabs @opentelemetry/api to register a W3CTraceContextPropagator and an AsyncLocalStorageContextManager. Application code uses the same package the way it's designed to be used:

• hooks.server.ts calls propagation.inject(context.active(), …) to stamp traceparent on responses so the browser can correlate a navigation with its backend trace;
• our API-client interceptors call trace.getActiveSpan() to set rpc.method/http.route span attributes and to put trace_id/span_id into structured logs.

So "needed on both sides" is the norm for @opentelemetry/api — and since it's a peer dependency of the SDK packages, it's very easy to end up with it only as a transitive dep, which is exactly how we (and presumably others) silently opt out of externalization.

We tested both PRs against the repro (packed @sveltejs/kit + @sveltejs/adapter-node straight from the branches; repro adapted to the v3 config/env API — defineEnvVars in src/env.js, named imports from $app/env/private):

#16302 — confirmed fixed. On the same Linux setup that reproduced the bug, the compiled build/instrumentation.server.js now starts with a bare import("@opentelemetry/api") and the app module evaluates after env init:

compiled instrumentation.server.js dynamic imports: [ '"@opentelemetry/api"' ]
[api-client] module evaluated; MY_BASE_URL = https://api.example
{ captured: 'https://api.example', live: 'https://api.example' }

#16303 — hit an issue: with adapter-node + an instrumentation file present, the server crashes at startup:

build/__sveltekit_env_init.js:2
import { set_env } from './env.js';
SyntaxError: The requested module './env.js' does not provide an export named 'set_env'

The facade generated in builder.js hardcodes import { set_env } from './env.js' relative to the entrypoint — but for adapter-node, build/env.js is the adapter's own runtime helper (export { env, env_prefix, timeout_env }), and kit's env module with set_env doesn't survive the adapter's bundling step at any stable relative path. Happy to re-test once that's adjusted.