{"record":{"id":"a193c904baca83cb","repo":"mihomo-party-org/clash-party","slug":"native-binding-not-found-bindingname","errorCode":null,"errorMessage":"Native binding not found: ${bindingName}","messagePattern":"Native binding not found: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"src/native/sysproxy/index.js","lineNumber":113,"sourceCode":"    join(resourcesPath, 'sidecar', bindingName),\n    join(resourcesPath, 'extra', 'sidecar', bindingName)\n  ]\n\n  for (const sidecarPath of searchPaths) {\n    if (existsSync(sidecarPath)) {\n      try {\n        nativeBinding = require(sidecarPath)\n        return nativeBinding\n      } catch (e) {\n        loadError = e\n      }\n    }\n  }\n\n  if (loadError) {\n    throw loadError\n  }\n  throw new Error(`Native binding not found: ${bindingName}`)\n}\n\nconst binding = loadBinding()\n\nmodule.exports.triggerManualProxy = binding.triggerManualProxy\nmodule.exports.triggerAutoProxy = binding.triggerAutoProxy\nmodule.exports.getSystemProxy = binding.getSystemProxy\nmodule.exports.getAutoProxy = binding.getAutoProxy\nmodule.exports.setSystemProxy = binding.setSystemProxy\nmodule.exports.setAutoProxy = binding.setAutoProxy\n","sourceCodeStart":95,"sourceCodeEnd":124,"githubUrl":"https://github.com/mihomo-party-org/clash-party/blob/911e090537acdf7c50bee1c3aebecc2ef119a8b5/src/native/sysproxy/index.js#L95-L124","documentation":"loadBinding() locates and requires the prebuilt sysproxy native binding chosen by bindingName(). It first probes several candidate paths (app resources, dev cwd, sidecar dirs); if every candidate fails to load or exist, it throws 'Native binding not found: <bindingName>'. Unlike error 90 this means the platform IS mapped, but the .node file is absent or failed to load at runtime.","triggerScenarios":"Running the app in development without having built/downloaded the native sidecar (extra/sidecar missing); a packaged app whose installer omitted .node files; the binary exists but dlopen fails (wrong libc, corrupted download) so every require attempt sets loadError then falls through; getResourcesPath() pointing to the wrong directory.","commonSituations":"Fresh clone where scripts/prepare.mjs was never run so extra/sidecar is unpopulated; antivirus quarantining the .node file; Electron rebuild mismatch between Node ABI of the binary and Electron runtime; users installing from a portable zip that skips native asset download.","solutions":["Run the repo's prepare script (node scripts/prepare.mjs) or pnpm install postinstall to download/build native sidecars into extra/sidecar.","Verify the file named in the error exists under extra/sidecar or the app's resources dir; if missing, rebuild the native module for your Electron version (electron-rebuild or the project's native build task).","If the file exists but still fails, inspect the swallowed loadError (earlier in loadBinding) for dlopen/ABI errors and rebuild against the matching libc/ABI.","Reinstall the packaged app with the full installer rather than a partial/portable artifact."],"exampleFix":"// before\nconst binding = loadBinding()\n// after\ntry {\n  const binding = loadBinding()\n} catch (e) {\n  console.error('sysproxy unavailable:', e.message)\n}","handlingStrategy":"try-catch","validationCode":"import { existsSync } from 'fs'\nimport { join } from 'path'\nconst name = 'sysproxy.linux-x64-gnu.node' // from bindingName()\nconst candidates = [join(process.resourcesPath || '', name), join(process.cwd(), 'extra', 'sidecar', name)]\nif (!candidates.some(existsSync)) console.error(`missing native binding ${name} — run scripts/prepare.mjs`)","typeGuard":null,"tryCatchPattern":"try {\n  const binding = loadBinding()\n} catch (e) {\n  if (e.message.startsWith('Native binding not found:')) {\n    console.error('Native sidecar missing; system proxy disabled.', e.message)\n    // continue with app features that do not need sysproxy\n  } else {\n    throw e\n  }\n}","preventionTips":["Always run scripts/prepare.mjs (or full pnpm install) after cloning before dev run.","Verify .node files are included in electron-builder extraResources config.","Rebuild native modules with the matching Electron ABI (electron-rebuild) after Electron upgrades.","Compare package/app checksums if binaries keep disappearing (antivirus)."],"tags":["native-module","missing-file","packaging","electron"],"backgroundTag":"native-binding-not-found","analyzedSha":"911e090537acdf7c50bee1c3aebecc2ef119a8b5","analyzedAt":"2026-08-30T13:00:49.174Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}