{"record":{"id":"5d9860633f3dd833","repo":"diegosouzapw/OmniRoute","slug":"tproxy-transparent-socket-addon-is-not-available","errorCode":null,"errorMessage":"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.","messagePattern":"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\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/mitm/tproxy/transparentSocket.ts","lineNumber":98,"sourceCode":"  return null;\n}\n\nconst cached: TransparentAddon | null = loadTransparentAddon();\n\n/** True when the TPROXY transparent-socket addon is loadable on this host. */\nexport function isTransparentSocketAvailable(): boolean {\n  return cached !== null;\n}\n\n/**\n * Create an IP_TRANSPARENT listening socket and return its fd for Node to adopt\n * via `server.listen({ fd })`. Throws a clear, actionable error when the addon\n * is unavailable (callers should check `isTransparentSocketAvailable()` first\n * and disable the TPROXY capture mode).\n */\nexport function createTransparentListenerFd(ip: string, port: number): number {\n  if (!cached) {\n    throw new Error(\n      \"TPROXY transparent-socket addon is not available. It is Linux-only and must be built \" +\n        \"(`npm run build:native:tproxy`, needs a C toolchain) or shipped as a prebuild; \" +\n        \"CAP_NET_ADMIN is required at runtime.\"\n    );\n  }\n  return cached.createTransparentListener(ip, port);\n}\n\n/**\n * Set SO_MARK on a socket fd (anti-loop). The TPROXY listener marks its OWN\n * upstream connections with the bypass mark so the mangle OUTPUT rule excludes\n * them and they are not re-intercepted. Throws when the addon is unavailable.\n */\nexport function setSocketMark(fd: number, mark: number): void {\n  if (!cached) {\n    throw new Error(\"TPROXY transparent-socket addon is not available (setSocketMark).\");\n  }\n  cached.setSocketMark(fd, mark);","sourceCodeStart":80,"sourceCodeEnd":116,"githubUrl":"https://github.com/diegosouzapw/OmniRoute/blob/a179ffed5bb2e0b883b9ae7214ce8717b2a94c4d/src/mitm/tproxy/transparentSocket.ts#L80-L116","documentation":"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.","triggerScenarios":"Thrown at src/mitm/tproxy/transparentSocket.ts:98 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":[],"exampleFix":null,"handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"a179ffed5bb2e0b883b9ae7214ce8717b2a94c4d","analyzedAt":"2026-08-25T18:35:09.898Z","schemaVersion":2},"datasetVersion":"2026-08-25T21:54:21.419Z"}