{"record":{"id":"b935f348bde73886","repo":"mihomo-party-org/clash-party","slug":"tun-is-enabled-but-insufficient-permissions-detect","errorCode":null,"errorMessage":"TUN is enabled but insufficient permissions detected, auto-disabling TUN...","messagePattern":"TUN is enabled but insufficient permissions detected, auto-disabling TUN\\.\\.\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"src/main/core/permissions.ts","lineNumber":361,"sourceCode":"    buttons: [okText],\n    defaultId: 0\n  })\n}\n\nexport async function validateTunPermissionsOnStartup(\n  _restartCore: () => Promise<void>\n): Promise<void> {\n  const { tun } = await getControledMihomoConfig()\n\n  if (!tun?.enable) {\n    return\n  }\n\n  const hasPermissions = await checkMihomoCorePermissions()\n\n  if (!hasPermissions) {\n    // 启动时没有权限，静默禁用 TUN，不弹窗打扰用户\n    managerLogger.warn(\n      'TUN is enabled but insufficient permissions detected, auto-disabling TUN...'\n    )\n    await patchControledMihomoConfig({ tun: { enable: false } })\n\n    const { mainWindow } = await import('../index')\n    mainWindow?.webContents.send('controledMihomoConfigUpdated')\n    ipcMain.emit('updateTrayMenu')\n\n    managerLogger.info('TUN auto-disabled due to insufficient permissions on startup')\n  } else {\n    managerLogger.info('TUN permissions validated successfully')\n  }\n}\n\nexport async function checkAdminRestartForTun(restartCore: () => Promise<void>): Promise<void> {\n  if (process.argv.includes('--admin-restart-for-tun')) {\n    managerLogger.info('Detected admin restart for TUN mode, auto-enabling TUN...')\n","sourceCodeStart":343,"sourceCodeEnd":379,"githubUrl":"https://github.com/mihomo-party-org/clash-party/blob/911e090537acdf7c50bee1c3aebecc2ef119a8b5/src/main/core/permissions.ts#L343-L379","documentation":"During startup validation, validateTunPermissionsOnStartup finds TUN enabled in the controlled mihomo config but checkMihomoCorePermissions() reports the core binary lacks the privileges (root/admin or CAP_NET_ADMIN) needed to create the TUN device. The app silently disables TUN via patchControledMihomoConfig({tun:{enable:false}}) and notifies the renderer, logging this warning instead of prompting the user.","triggerScenarios":"App starts with tun.enable=true in the controlled config while the mihomo core binary is not setuid-root / not run as admin / lacks CAP_NET_ADMIN; typically after a fresh install, binary auto-update replacing a privileged binary, or moving data to another machine.","commonSituations":"User enabled TUN previously, then the core was updated and lost its setuid bit/capabilities; running on Linux without granting cap_net_admin; switching from an admin-launched instance to a normal one on Windows/macOS.","solutions":["Re-grant privileges to the core binary (e.g. run the app's admin-restart flow checkAdminRestartForTun, or `setcap cap_net_admin,cap_net_bind_service=+ep` on Linux / setuid root on macOS).","After privileges are restored, re-enable TUN (patchControledMihomoConfig({tun:{enable:true}})) and restart the core.","If TUN is not needed, ignore — TUN was auto-disabled intentionally and traffic falls back to system proxy."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"const enabled = (await getControledMihomoConfig()).tun?.enable\nif (enabled && !(await checkMihomoCorePermissions())) {\n  await grantCorePermissions() // setcap / setuid / admin relaunch before starting core\n}","typeGuard":null,"tryCatchPattern":"try {\n  await validateTunPermissionsOnStartup()\n} catch (e) {\n  logger.error('TUN validation crashed; forcing TUN off for safety', e)\n  await patchControledMihomoConfig({ tun: { enable: false } })\n}","preventionTips":["After every core binary update, re-run the permission grant step before enabling TUN.","Surface a UI hint when TUN is requested but permissions are absent, instead of relying on silent auto-disable.","On Linux, verify cap_net_admin on the binary during packaging/installation."],"tags":["tun","permissions","startup","mihomo"],"backgroundTag":"insufficient-permissions-tun","analyzedSha":"911e090537acdf7c50bee1c3aebecc2ef119a8b5","analyzedAt":"2026-08-30T13:00:49.174Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}