diegosouzapw/OmniRoute · error

TPROXY transparent-socket addon is not available. It is Linu

Error message

TPROXY transparent-socket addon is not available. It is Linux-only and must be built (`npm run build:native:tproxy`, needs a C toolchain) or shipped as a prebuild; CAP_NET_ADMIN is required at runtime.

What it means

Error "TPROXY transparent-socket addon is not available. It is Linux-only and must be built (`npm run build:native:tproxy`, needs a C toolchain) or shipped as a prebuild; CAP_NET_ADMIN is required at runtime." thrown in diegosouzapw/OmniRoute.

Source

Thrown at src/mitm/tproxy/transparentSocket.ts:98

  return null;
}

const cached: TransparentAddon | null = loadTransparentAddon();

/** True when the TPROXY transparent-socket addon is loadable on this host. */
export function isTransparentSocketAvailable(): boolean {
  return cached !== null;
}

/**
 * Create an IP_TRANSPARENT listening socket and return its fd for Node to adopt
 * via `server.listen({ fd })`. Throws a clear, actionable error when the addon
 * is unavailable (callers should check `isTransparentSocketAvailable()` first
 * and disable the TPROXY capture mode).
 */
export function createTransparentListenerFd(ip: string, port: number): number {
  if (!cached) {
    throw new Error(
      "TPROXY transparent-socket addon is not available. It is Linux-only and must be built " +
        "(`npm run build:native:tproxy`, needs a C toolchain) or shipped as a prebuild; " +
        "CAP_NET_ADMIN is required at runtime."
    );
  }
  return cached.createTransparentListener(ip, port);
}

/**
 * Set SO_MARK on a socket fd (anti-loop). The TPROXY listener marks its OWN
 * upstream connections with the bypass mark so the mangle OUTPUT rule excludes
 * them and they are not re-intercepted. Throws when the addon is unavailable.
 */
export function setSocketMark(fd: number, mark: number): void {
  if (!cached) {
    throw new Error("TPROXY transparent-socket addon is not available (setSocketMark).");
  }
  cached.setSocketMark(fd, mark);

View on GitHub (pinned to a179ffed5b)

When it happens

Trigger: Thrown at src/mitm/tproxy/transparentSocket.ts:98 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of diegosouzapw/OmniRoute@a179ffed5b (2026-08-25). Data as JSON: /api/errors/5d9860633f3dd833. Report an issue: GitHub.