{"record":{"id":"d9c8c249e0b19ba1","repo":"slackhq/nebula","slug":"failed-to-load-module-library-s","errorCode":null,"errorMessage":"failed to load module library: %s","messagePattern":"failed to load module library: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkclient/pkclient_cgo.go","lineNumber":33,"sourceCode":"\ntype PKClient struct {\n\tmodule     p11.Module\n\tsession    p11.Session\n\tid         []byte\n\tlabel      []byte\n\tprivKeyObj p11.Object\n\tpubKeyObj  p11.Object\n}\n\ntype ecdsaSignature struct {\n\tR, S *big.Int\n}\n\n// New tries to open a session with the HSM, select the slot and login to it\nfunc New(hsmPath string, slotId uint, pin string, id string, label string) (*PKClient, error) {\n\tmodule, err := p11.OpenModule(hsmPath)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to load module library: %s\", hsmPath)\n\t}\n\n\tslots, err := module.Slots()\n\tif err != nil {\n\t\tmodule.Destroy()\n\t\treturn nil, err\n\t}\n\n\t// Try to open a session on the slot\n\tslotIdx := 0\n\tfor i, slot := range slots {\n\t\tif slot.ID() == slotId {\n\t\t\tslotIdx = i\n\t\t\tbreak\n\t\t}\n\t}\n\n\tclient := &PKClient{","sourceCodeStart":15,"sourceCodeEnd":51,"githubUrl":"https://github.com/slackhq/nebula/blob/dd8f660c0ac37903ec4080ca4d3c861ba9342ceb/pkclient/pkclient_cgo.go#L15-L51","documentation":"New() failed to load the PKCS#11 module shared library via p11.OpenModule(hsmPath); the original error is discarded and the path is reported with %s. The library throws this because the HSM vendor PKCS#11 library could not be dlopen'd (missing file, bad architecture, or missing dependencies).","triggerScenarios":"Calling New() with an hsmPath that does not exist, is not a valid shared library, has the wrong architecture (32/64-bit), or whose transitive dependencies are missing — the pkcs11 package returns CKR_FUNCTION/OS load error.","commonSituations":"Wrong path to the vendor .so/.dll in config; Linux binary using a module compiled for another platform; missing vendor runtime deps; using a Windows p11 library path on Linux or vice versa.","solutions":["Verify hsmPath points to the real PKCS#11 library file (ldd/path check)","Run `ldd <module.so>` to find missing transitive dependencies","Match library architecture to the binary (64-bit vs 32-bit)","Install the vendor PKCS#11 library (e.g. opensc, softhsm2, vendor SDK)","Temporarily modify/strace the open call to capture the raw OS error since it is swallowed here"],"exampleFix":"// before\npkcs11_library: /usr/lib/libsofthsm2.so\n// after (find the real path)\nfind / -name 'libsofthsm2.so*'\npkcs11_library: /usr/lib/softhsm/libsofthsm2.so","handlingStrategy":"validation","validationCode":"// verify the module library exists and is loadable before New()\nif _, err := os.Stat(hsmPath); err != nil {\n    return fmt.Errorf(\"PKCS#11 module not found: %s\", hsmPath)\n}\nif out, err := exec.Command(\"ldd\", hsmPath).CombinedOutput(); err != nil || strings.Contains(string(out), \"not found\") {\n    return fmt.Errorf(\"PKCS#11 module has missing deps:\\n%s\", out)\n}","typeGuard":null,"tryCatchPattern":"client, err := pkclient.New(hsmPath, slot, pin, id, label)\nif err != nil && strings.Contains(err.Error(), \"failed to load module library\") {\n    return fmt.Errorf(\"check hsmPath/architecture/deps for %s: %w\", hsmPath, err)\n}","preventionTips":["Resolve the module's absolute path in config","Match 64-bit module with 64-bit binary","Run ldd (or dumpbin) on the vendor .so/.dll before deploy","Install vendor runtime dependencies on hosts","Note the raw load error is swallowed; verify the path manually"],"tags":["pkcs11","hsm","shared-library","load-failure"],"backgroundTag":"pkcs11-module-load-failed","analyzedSha":"dd8f660c0ac37903ec4080ca4d3c861ba9342ceb","analyzedAt":"2026-09-03T11:13:55.444Z","contentChangedAt":"2026-09-03T11:13:55.444Z","schemaVersion":2},"datasetVersion":"2026-09-10T17:17:09.494Z"}