mihomo-party-org/clash-party · critical · Error

Native binding not found: ${bindingName}

Error message

Native binding not found: ${bindingName}

What it means

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.

Source

Thrown at src/native/sysproxy/index.js:113

    join(resourcesPath, 'sidecar', bindingName),
    join(resourcesPath, 'extra', 'sidecar', bindingName)
  ]

  for (const sidecarPath of searchPaths) {
    if (existsSync(sidecarPath)) {
      try {
        nativeBinding = require(sidecarPath)
        return nativeBinding
      } catch (e) {
        loadError = e
      }
    }
  }

  if (loadError) {
    throw loadError
  }
  throw new Error(`Native binding not found: ${bindingName}`)
}

const binding = loadBinding()

module.exports.triggerManualProxy = binding.triggerManualProxy
module.exports.triggerAutoProxy = binding.triggerAutoProxy
module.exports.getSystemProxy = binding.getSystemProxy
module.exports.getAutoProxy = binding.getAutoProxy
module.exports.setSystemProxy = binding.setSystemProxy
module.exports.setAutoProxy = binding.setAutoProxy

View on GitHub (pinned to 911e090537)

Solutions

1. Run the repo's prepare script (node scripts/prepare.mjs) or pnpm install postinstall to download/build native sidecars into extra/sidecar.
2. 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).
3. 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.
4. Reinstall the packaged app with the full installer rather than a partial/portable artifact.

Example fix

// before
const binding = loadBinding()
// after
try {
  const binding = loadBinding()
} catch (e) {
  console.error('sysproxy unavailable:', e.message)
}

import { existsSync } from 'fs'
import { join } from 'path'
const name = 'sysproxy.linux-x64-gnu.node' // from bindingName()
const candidates = [join(process.resourcesPath || '', name), join(process.cwd(), 'extra', 'sidecar', name)]
if (!candidates.some(existsSync)) console.error(`missing native binding ${name} — run scripts/prepare.mjs`)

try {
  const binding = loadBinding()
} catch (e) {
  if (e.message.startsWith('Native binding not found:')) {
    console.error('Native sidecar missing; system proxy disabled.', e.message)
    // continue with app features that do not need sysproxy
  } else {
    throw e
  }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unsupported platform: ${platform}-${arch}

AI-assisted analysis of mihomo-party-org/clash-party@911e090537 (2026-08-30). Data as JSON: /api/errors/a193c904baca83cb. Report an issue: GitHub.