Skip to content

go-kuzu library fails to load the dynamic library

Summary

The go-kuzu dependency requires dynamically linked shared libraries (libkuzu.so) that are not available when the compiled binary is executed in different environments, causing runtime failures.

Problem Description

When building gitlab-zoekt with the go-kuzu dependency, the resulting binary works in the build environment but fails when deployed to clean environments (containers, CI/CD, customer installations) because it cannot find the required shared library.

Current Impact

  • Breaks deployment to clean Docker containers
  • Affects CNG, Rails tests, Omnibus, and SM customer deployments
  • Prevents building truly portable standalone binaries

Steps to Reproduce

  1. Build the binary in a container:

    docker run --rm -v $(pwd):/app -it golang:1.25 sh -c "cd /app && make build-unified"

  2. Try to run the binary in a fresh container:

    docker run --rm -v $(pwd):/app -it golang:1.25 sh -c "/app/bin/gitlab-zoekt help"

Expected Behavior

The binary should run successfully in any environment without requiring additional shared libraries.

Actual Behavior

/app/bin/gitlab-zoekt: error while loading shared libraries: libkuzu.so: cannot open shared object file: No such file or directory

Technical Details

  • The shared library is present during build: /go/pkg/mod/github.com/kuzudb/go-kuzu@v0.11.1/lib/dynamic/linux-amd64/libkuzu.so
  • Setting CGO_ENABLED=1 doesn't resolve the dynamic linking issue
  • Binary works immediately after compilation because the shared library is available in the build environment

Proposed Solution

Use statically linked bindings from our existing Rust knowledge-graph project:

Affected Components

  • gitlab-zoekt binary distribution
  • All deployment environments (CNG, Rails tests, Omnibus, SM)
  • Any environment where the binary runs separately from the build environment