TUN is enabled but insufficient permissions detected, auto-d

Error message

TUN is enabled but insufficient permissions detected, auto-disabling TUN...

What it means

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.

Source

Thrown at src/main/core/permissions.ts:361

    buttons: [okText],
    defaultId: 0
  })
}

export async function validateTunPermissionsOnStartup(
  _restartCore: () => Promise<void>
): Promise<void> {
  const { tun } = await getControledMihomoConfig()

  if (!tun?.enable) {
    return
  }

  const hasPermissions = await checkMihomoCorePermissions()

  if (!hasPermissions) {
    // 启动时没有权限，静默禁用 TUN，不弹窗打扰用户
    managerLogger.warn(
      'TUN is enabled but insufficient permissions detected, auto-disabling TUN...'
    )
    await patchControledMihomoConfig({ tun: { enable: false } })

    const { mainWindow } = await import('../index')
    mainWindow?.webContents.send('controledMihomoConfigUpdated')
    ipcMain.emit('updateTrayMenu')

    managerLogger.info('TUN auto-disabled due to insufficient permissions on startup')
  } else {
    managerLogger.info('TUN permissions validated successfully')
  }
}

export async function checkAdminRestartForTun(restartCore: () => Promise<void>): Promise<void> {
  if (process.argv.includes('--admin-restart-for-tun')) {
    managerLogger.info('Detected admin restart for TUN mode, auto-enabling TUN...')

View on GitHub (pinned to 911e090537)

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.

Defensive patterns

Strategy: validation

Validate before calling

const enabled = (await getControledMihomoConfig()).tun?.enable
if (enabled && !(await checkMihomoCorePermissions())) {
  await grantCorePermissions() // setcap / setuid / admin relaunch before starting core
}

Try / catch

try {
  await validateTunPermissionsOnStartup()
} catch (e) {
  logger.error('TUN validation crashed; forcing TUN off for safety', e)
  await patchControledMihomoConfig({ tun: { enable: false } })
}

Prevention

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.

When it happens

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

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

Related errors

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