paperclipai/paperclip · error · Error

native SO_PEERCRED is supported only on Linux

Error message

native SO_PEERCRED is supported only on Linux

What it means

Platform gate in createNativePeerCredentialReader: the N-API addon that reads SO_PEERCRED could not be loaded/initialized, or the process is running on a non-Linux platform where SO_PEERCRED does not exist. The Unix-socket peer-credential model is Linux-only, so the broker cannot provide its core admission guarantee here.

Source

Thrown at packages/tailscale-https-broker/src/native-peercred.ts:23

 * build compiles a dependency-free N-API addon next to this module's emitted
 * JavaScript. The native call is synchronous and runs once per accepted local
 * socket, before the connection enters the admission pool.
 */
import { createRequire } from "node:module";
import type { Socket } from "node:net";
import type { PeerCredentials } from "./types.js";

interface NativePeercredBinding {
  getPeerCredentials(fd: number): PeerCredentials;
}

interface SocketWithHandle extends Socket {
  _handle?: { fd?: unknown };
}

export function createNativePeerCredentialReader(): (socket: Socket) => PeerCredentials {
  if (process.platform !== "linux") {
    throw new Error("native SO_PEERCRED is supported only on Linux");
  }

  const require = createRequire(import.meta.url);
  const binding = require("./peercred-native.node") as NativePeercredBinding;

  return (socket: Socket): PeerCredentials => {
    const fd = (socket as SocketWithHandle)._handle?.fd;
    if (!Number.isInteger(fd) || (fd as number) < 0) {
      throw new Error("accepted socket has no valid file descriptor");
    }
    return binding.getPeerCredentials(fd as number);
  };
}

View on GitHub (pinned to 120ae5428f)

Solutions

1. Run the broker on Linux to use native SO_PEERCRED, or disable the native peercred path on other platforms.

When it happens

Trigger: Thrown at packages/tailscale-https-broker/src/native-peercred.ts:23 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@120ae5428f (2026-08-18). Data as JSON: /api/errors/2a2297435a1a9c15. Report an issue: GitHub.