ComposioHQ/composio · critical · KeyringError

PlatformFailure

PlatformFailure

Error message

dlopen(${path}) failed

What it means

The macOS keyring FFI layer called dlopen on a system library path and got a NULL handle, meaning the dynamic library could not be loaded. KeyringError kind 'PlatformFailure' with cause 'dlopen(<path>) failed'.

Solutions

1. Verify you are on macOS and the library path exists
2. Disable library validation restrictions or run outside the restricting sandbox
3. Use a platform-appropriate store for your OS

import { platform } from 'node:process';
if (platform !== 'darwin') throw new Error('macOS-only store');

const isDarwin = (): boolean => process.platform === 'darwin';

catch (e) { if (e instanceof KeyringError && e.kind === 'PlatformFailure') { /* fall back to file store */ } else throw e; }

When it happens

Trigger: Loading libSystem/CoreFoundation via FFI on a system where the path is wrong, the library is blocked (sandbox/hardened runtime), or running on a non-macOS platform.

Common situations: Sandboxed processes, changed library paths after macOS updates, or accidentally executing the macOS store on Linux/Windows.

Related errors

• CFDataGetBytePtr returned NULL
• CFDictionaryCreateMutable returned NULL
• CFStringCreateWithBytes returned NULL
• dlsym( ) failed
• BadDataFormat

AI-assisted analysis of ComposioHQ/composio@64b1b85502 (2026-08-28). Data as JSON: /api/errors/41236b8fc78df0e1. Report an issue: GitHub.

Appendix: source

Thrown at ts/packages/cli-keyring/src/stores/macos-security-ffi.ts:86

// Low-level dlopen / dlsym (used to resolve `kSec*` / `kCF*` extern const
// data symbols that `bun:ffi`'s normal dlopen surface doesn't expose).
// -----------------------------------------------------------------------------

const LIBSYSTEM = '/usr/lib/libSystem.B.dylib';
const SECURITY_FRAMEWORK = '/System/Library/Frameworks/Security.framework/Security';
const CORE_FOUNDATION = '/System/Library/Frameworks/CoreFoundation.framework/CoreFoundation';

const RTLD_NOW = 0x2;

const libSystem = dlopen(LIBSYSTEM, {
  dlopen: { args: [FFIType.ptr, FFIType.i32], returns: FFIType.u64 },
  dlsym: { args: [FFIType.u64, FFIType.ptr], returns: FFIType.u64 },
});

function dlopenRaw(path: string): bigint {
  const handle = libSystem.symbols.dlopen(cstr(path), RTLD_NOW);
  if (handle === 0n) {
    throw new KeyringError({
      kind: 'PlatformFailure',
      cause: new Error(`dlopen(${path}) failed`),
    });
  }
  return handle;
}

/**
 * Resolve an extern const CFTypeRef data symbol: `dlsym` returns the
 * address of the storage slot (i.e. a pointer-to-pointer); we
 * dereference one level via `read.ptr` to get the actual CFTypeRef
 * value stored there. The symbol is stable for the process lifetime,
 * so caching the resolved BigInt is safe.
 */
function dlsymCFConstant(handle: bigint, name: string): bigint {
  const addr = libSystem.symbols.dlsym(handle, cstr(name));
  if (addr === 0n) {
    throw new KeyringError({

View on GitHub (pinned to 64b1b85502)