[Bug]: rocksdb-native prebuilds DT_NEEDED-link libatomic.so.1; worker cannot start on slim Linux images (follow-up to #3853)

[hevans714]

Split out of #3853 at @victorchimakanu's request in the closing comment there: "Worth a focused
issue scoped to rocksdb-native's DT_NEEDED." This is that issue. The tree-wide preflight named
alongside it is deliberately not in scope here — it is the class, this is one instance.

Summary

rocksdb-native's Linux prebuilds declare libatomic.so.1 as a required shared library.
libatomic1 is not installed in node:22-slim, debian:12-slim or ubuntu:24.04, so on a
clean slim image the bare worker aborts during startup and no model of any modality will
load — the same failure shape as the libvulkan half of #3853, on an unrelated package.

This is not covered by the fix that closed #3853. @qvac/diffusion-cpp 0.21.0 makes the Vulkan
backend a dlopen'd module, which resolves that instance. rocksdb-native is untouched by it.

Reproduction

Clean node:22-slim, npm install -g @qvac/cli@0.12.0 (resolves @qvac/sdk 0.18.x), with
libvulkan1 already installed so the #3853 workaround is in place:

[cause]: Error: libatomic.so.1: cannot open shared object file: No such file or directory
    at require.addon (bare-module/index.js:822:30)
    at rocksdb-native/binding.js:3:26
  code: 'CANNOT_LOAD',
  href: 'file:///usr/local/.../rocksdb-native/prebuilds/linux-arm64/rocksdb-native.bare'
...
code: 50204

apt-get install -y libatomic1 fixes it — same shape as the libvulkan1 workaround.

The trace stops at rocksdb-native/lib/column-family.js, so all we can support is that the load
happens during worker startup. We cannot say from the trace which package triggers it; see
"What we cannot say" below.

Verified against the currently published artifacts (2026-09-06)

rocksdb-native is still 3.17.4 — the same version as when this was first reported on
#3853 (2026-08-24), so nothing has moved underneath it. We unpacked the published tarball and
parsed the DT_NEEDED entries out of each prebuild's ELF .dynamic section rather than reading
a changelog:

prebuild	DT_NEEDED
linux-arm64/rocksdb-native.bare	libatomic.so.1, libstdc++.so.6, libm.so.6, libgcc_s.so.1, libc.so.6
linux-arm64/rocksdb-native.node	libatomic.so.1, libstdc++.so.6, libm.so.6, libgcc_s.so.1, libc.so.6
linux-x64/rocksdb-native.bare	libatomic.so.1, libstdc++.so.6, libm.so.6, libgcc_s.so.1, libc.so.6, ld-linux-x86-64.so.2
linux-x64/rocksdb-native.node	libatomic.so.1, libstdc++.so.6, libm.so.6, libgcc_s.so.1, libc.so.6, ld-linux-x86-64.so.2

Two details that were not in the original report:

• It is all four Linux artifacts, both architectures and both the .bare and .node
  flavours — not just the arm64 .bare the original trace happened to name.
• It is Linux-specific. The android-arm64 and android-x64 prebuilds link
  libc++_shared.so and need no libatomic; darwin, iOS and win32 are unaffected. So this is a
  property of how the Linux prebuilds are linked, not of the source.

Why the #3853 fix does not cover this

rocksdb-native is not a modality plugin addon at all — it is not among the 13 */plugin
subpaths @qvac/sdk exports on main. It arrives through the storage family, which the SDK
depends on directly.

(The packages/bare-sdk/scripts/plugin-addons.mjs list referenced earlier on #3853 no longer
exists on main — packages/bare-sdk is gone — so the plugin subpath exports are the current
equivalent.) Confirmed against @qvac/sdk 0.18.2 as published:

@qvac/registry-client ^0.6.1     corestore  ^7.4.5
hyperdrive            ^13.0.1    hyperswarm ^4.14.0

and hyperdb (rocksdb-native@^3.0.0) and hypercore-storage (rocksdb-native@^3.11.0) each
declare it directly — they are siblings, not a chain.

The consequence for whoever picks this up: a guard scoped to the plugin addon list, or a lazy
plugin-import fix, would not have caught this. That is the substance of @victorchimakanu's
2026-08-25 comment on #3853 — two system libraries, two unrelated addon families, the second one
found on a clean image of the release published that same morning.

What we cannot say

Which of the four paths actually triggers the load. There is more than one route to the same
prebuild and the stack trace does not name the caller. We are not claiming it is hyperdb, and
an earlier version of this report said "hyperdb → hypercore-storage", which was wrong and
was corrected on the original thread.

Possible fixes, in the order we would want them

1. Link it statically or drop the dependency. libatomic is usually pulled in when the
   compiler emits calls to __atomic_* helpers for wide or unaligned atomics rather than
   inlining them. -Wl,--as-needed plus libatomic.a, or raising the target so the atomics
   inline, would remove the runtime requirement entirely. This is the only fix that needs
   nothing from operators.
2. Document it. If the link is load-bearing, libatomic1 belongs next to libvulkan1 in
   whatever install guidance ships for slim images.
3. Fail usefully. QVAC-23774 fix: surface preload failure cause and refuse to start when all preloads fail #4129 improved this by surfacing worker stderr instead of only the timeout,
   which is what made this one findable at all. A startup check that names the addon and the
   missing library would turn a 30-second mystery into a one-line message.

Environment

• node:22-slim, @qvac/cli@0.12.0, @qvac/sdk 0.18.x, rocksdb-native 3.17.4

• linux/arm64 (Docker on Apple Silicon) and linux/amd64 (Ubuntu 24.04, 2 vCPU / 7 GB, no GPU,
  no graphics stack) — both reproduce, both are fixed by libatomic1

• Base images re-checked 2026-09-06, both architectures. In every case the libatomic1
  package is not installed, libatomic.so.1 is not resolvable by the loader, and no copy of the
  file exists anywhere on the filesystem:

  image	linux/arm64	linux/amd64
  node:22-slim	absent	absent
  debian:12-slim	absent	absent
  ubuntu:24.04	absent	absent

• The DT_NEEDED table above was re-verified against the published tarball on 2026-09-06. The
  runtime trace under "Reproduction" is from a real install on 2026-08-24; rocksdb-native has
  not been republished since, so the static facts above describe that same artifact.

Offer

Same standing offer as on #3853, and it still holds. We run QVAC in production on CPU-only boxes
in both architectures with a real cross-language workload. Stripping a library from a warm image
takes about a second, so we can run a patched build against the empty-libatomic1 case in both
arches the same day. Say the word and it is yours.

[victorchimakanu]

This is the focused issue the #3853 close asked for, and it is complete enough to route as it stands. Checked against the published packages this morning: rocksdb-native is still 3.17.4 on npm (last modified 11 August), hyperdb declares it at ^3.0.0 and hypercore-storage at ^3.11.0, and published @qvac/sdk 0.18.2 depends on corestore ^7.4.5, hyperdrive ^13.0.1, hyperswarm ^4.14.0 and @qvac/registry-client ^0.6.1 directly, none of which is a plugin subpath. So the chain you describe holds and a guard scoped to the plugin addon list cannot see it.

One fact that shapes the fix order. rocksdb-native is a Holepunch package (github.com/holepunchto/rocksdb-native), not one this repo builds, so your first option, linking libatomic statically or raising the target so the atomics inline, is an upstream change and I cannot promise it from here. The second and third are ours. A libatomic1 line next to libvulkan1 in the slim image guidance costs nothing and I will push for it as the immediate fix. On the third, #4159 landed on main on 3 September and gives a worker startup failure a typed cause, which is the natural place for a check that names the addon and the missing library. I have not verified that it does that today, so treat it as the hook, not the fix.

I am routing this to the team as a confirmed report with your DT_NEEDED table as the evidence. Your standing offer is accepted. When there is a patched build or a documented image to test, I will say so here, and the empty libatomic1 run on both architectures is exactly the check we want.

[hevans714]

Filed upstream as requested: holepunchto/rocksdb-native#109.

holepunchto/rocksdb-native#109

It carries the same DT_NEEDED table, but re-derived against rocksdb-native alone — no part of the QVAC stack installed — so the maintainers do not have to take a downstream report on faith. Three things came out of doing it that way and are worth having on this thread too.

1. The error message points away from the cause. On a clean node:22-slim, require('rocksdb-native') reports:

Error: Cannot find addon '.' imported from '.../rocksdb-native/binding.js'
Candidates:
- .../prebuilds/linux-x64/rocksdb-native.node

That candidate exists and is 11,227,408 bytes. process.dlopen() on that exact path says:

libatomic.so.1: cannot open shared object file: No such file or directory

So a missing shared library surfaces as a missing addon, and the reader goes looking for a packaging or platform-detection fault. This is the same class as #4129 one layer down, and it is most of why the original diagnosis on #3853 took as long as it did. It is raised upstream as a fix worth making independently of the linking question.

2. The platform split supports the linking theory. Parsing every prebuild rather than the Linux four: the Android artifacts link libc++_shared.so and need no libatomic; darwin, iOS and win32 are not ELF. All four Linux artifacts need it, both arches, both .bare and .node. And libatomic is never named in the project's CMakeLists.txt, so it arrives implicitly — most likely from the vendored rocksdb target emitting __atomic_* helper calls rather than from binding.cc. That is what makes option 1 (static link, or raise the target so the atomics inline) plausible rather than speculative.

3. Nothing has moved. rocksdb-native is still 3.17.4, published 2026-08-11 and still latest. main has had only workflow-permission commits since (accb1df7, 1e5a3f78), neither touching the build or the linking — so the report describes main as well as the release. Re-verified 2026-09-07, both arches, along with the three base images.

Repro and fix confirmed on linux/amd64 and linux/arm64 today; apt-get install -y libatomic1 resolves it on both.

[victorchimakanu]

Both of the parts I said were ours are now open as pull requests. localhost41 opened them overnight and neither was requested, so it is worth pointing you at them rather than letting them land without the person who reported this seeing them.

#4331 is the documentation half. It adds libatomic.so.1 to the Linux section of system-requirements.mdx with the apt install -y libatomic1 command and a note that it is needed even for CPU only inference, and it adds a "Startup failure: missing libatomic.so.1" entry to troubleshooting.mdx that names the loader line, says the top level error may report an RPC initialization timeout and to check error.cause, and links back to this issue.

#4332 is the diagnostic half, in the place I said it would go. createRPCInitTimeoutCause now looks in the worker stderr tail for the loader sentence and, when it finds it, appends a line naming libatomic1 to the WorkerStartupError message. Reading the diff: stderrTail, exitCode and workerExited are untouched, and a second test asserts that libvulkan.so.1, a libatomic version mismatch, and a plain missing addon message do not get the hint.

One thing to confirm on your side. The hint matches on the literal string libatomic.so.1: cannot open shared object file: No such file or directory, and the trace in this issue carries that sentence on [cause], so it should fire on your image. The author could not run a Linux container while working on it, so a run on the node:22-slim box you already have is the only way to know it fires where it actually matters. If it does not fire, the reason belongs on that PR.

Your upstream filing at holepunchto/rocksdb-native#109 covers the linking option, which is the one of the three that is not ours to make.

What none of this covers is the class rather than the instance. Nothing walks DT_NEEDED across every native prebuild in the tree, so the next library like this one gets found the way this one was found, by someone running into it on a clean image. That is still unfiled and I will say so where it can be picked up.

[hevans714]

Filed the class-level gap you named here as #4356 — the tree-wide DT_NEEDED preflight, proposed as a qvac doctor check.

It goes up with a working prototype and its output rather than just the idea, because building one turned out to teach more than proposing it would have. Two things worth pulling out for this thread:

It rediscovers this issue without starting a worker. 60 native binaries scanned on the release image with libatomic1 removed; libatomic.so.1 comes back UNRESOLVED against rocksdb-native's .bare and .node. Static read of files already on disk — no worker, no model, no GPU.

The obvious implementation would have false-positived on your own tree. My first version judged everything by ldconfig and reported four missing libraries. Two were wrong: libva.so.2 and libva-drm.so.2 are absent from node:22-slim and from ldconfig, and resolve fine because bare-ffmpeg ships them beside itself under $ORIGIN. Nearly every QVAC addon sets RUNPATH as $ORIGIN/<name>@<version>:$ORIGIN/<name>. A checker that does not expand that reports working installs as broken, which is worse than no checker. The corrected resolution order is in the issue.

There is also one entry the scan flags that I have deliberately not filed as a bug — a DT_NEEDED on qvac__fabric@0.bare from two packages, where no file of that name exists in the tree. It may be entirely fine if Bare resolves addon-to-addon links itself rather than through the ELF loader, and I cannot settle that from outside the runtime. It is in #4356 as a question for someone who knows Bare, because either answer changes what the check has to do.

[hevans714]

The diagnostic half of this is fixed upstream, in a different package than I thought.

require-addon 1.3.0 now throws CANNOT_LOAD when a prebuild exists but fails to load, with the
loader error as the cause, instead of reporting it as a missing addon. Same repro as above, on
node:22-slim with no libatomic1:

before   ADDON_NOT_FOUND  "Cannot find addon '.' imported from '…/binding.js'"
         cause: MODULE_NOT_FOUND  "Cannot find module '/prebuilds/linux-x64/rocksdb-native.node'"

after    CANNOT_LOAD      "Cannot load addon '…/rocksdb-native/prebuilds/linux-x64/rocksdb-native.node'"
         cause: "libatomic.so.1: cannot open shared object file: No such file or directory"

holepunchto/require-addon#6 → holepunchto/require-addon#7, released as 1.3.0.

Two corrections to what I said about this earlier, both mine.

It was not swallowing the error, it was overwriting it. lib/node.js kept cause across the
whole candidate loop. The real file is candidate 1 of 10; it failed with the libatomic message,
that was captured, and then eight further candidates that never existed replaced it — the last
being a MODULE_NOT_FOUND on a path outside the package. The useful error was there and was
discarded between being caught and being reported.

It was the Node loader only. lib/bare.js is one line delegating to Bare's own
require.addon, so under Bare — which is what the QVAC worker runs — this already surfaced
correctly as CANNOT_LOAD with the loader message. I described my Node-side reproduction as
though it explained why #3853 was slow to diagnose. It did not; that failure was already legible
on the runtime you actually use.

So this changes nothing for the worker path, and it does mean a Node consumer hitting the same
missing library now gets told which library and which file, without the stack having to be read.

libatomic itself remains an expected, documented dependency — the rocksdb-native README says so
on line 10, which I should have read before filing there. That one was mine too.

[victorchimakanu]

require-addon 1.3.0 is live on npm and is latest as of today.

It reaches QVAC users without a bump anywhere. rocksdb-native@3.17.4 declares require-addon: "^1.0.2", so a fresh install resolves 1.3.0 and the CANNOT_LOAD error with the loader message on cause arrives with it.

Your second correction is the one worth keeping on this thread. The worker runs Bare, lib/bare.js is a one line delegate to Bare's own require.addon, so the worker path already reported this correctly and 1.3.0 does not change it. What changes is the Node side, where the real candidate's failure was being overwritten by eight later candidates that never existed.

That leaves the two open pieces here where they were. The tree wide static walk is #4337. The startup message hint is #4332, which reads the worker stderr tail on the RPC init timeout path rather than the loader error, so 1.3.0 does not overlap it.