netchx/netch · critical · MessageException

builtin driver files missing, can't install NF driver

Error message

builtin driver files missing, can't install NF driver

What it means

Thrown by NFController.InstallDriver when Constants.NFDriver (bin\nfdriver.sys) does not exist on disk, so the netfilter2 driver cannot be copied to the system drivers directory. This fires during CheckDriver when the installed driver is missing or outdated and a (re)install is required.

Source

Thrown at Netch/Controllers/NFController.cs:202

        if (!reinstall)
            return;

        Log.Information("Update netfilter2 driver");
        UninstallDriver();
        InstallDriver();
    }

    /// <summary>
    ///     安装 NF 驱动
    /// </summary>
    /// <returns>驱动是否安装成功</returns>
    private static void InstallDriver()
    {
        Log.Information("Install netfilter2 driver");
        Global.MainForm.StatusText(i18N.Translate("Installing netfilter2 driver"));

        if (!File.Exists(Constants.NFDriver))
            throw new MessageException(i18N.Translate("builtin driver files missing, can't install NF driver"));

        try
        {
            File.Copy(Constants.NFDriver, SystemDriver);
        }
        catch (Exception e)
        {
            Log.Error(e, "Copy netfilter2.sys failed\n");
            throw new MessageException($"Copy netfilter2.sys failed\n{e.Message}");
        }

        // 注册驱动文件
        if (Interops.Redirector.aio_register("netfilter2"))
        {
            Log.Information("Install netfilter2 driver finished");
        }
        else
        {

View on GitHub (pinned to 9d99eb1c5a)

Solutions

Confirm bin\nfdriver.sys exists under NetchDir.
Re-download/re-extract the official release to restore nfdriver.sys.
Add an antivirus exclusion for the Netch directory and restore the file.
Re-run Start so CheckDriver can complete the install.

Defensive patterns

Strategy: validation

Validate before calling

string driver = Path.Combine(Global.NetchDir, Constants.NFDriver);
if (!File.Exists(driver))
    throw new MessageException($"{Constants.NFDriver} is missing; reinstall Netch to restore the netfilter2 driver.");

Try / catch

try { /* NFController.CheckDriver path */ }
catch (MessageException ex) when (ex.Message.Contains("builtin driver files missing"))
{
    OfferReinstall("The bundled nfdriver.sys is missing and must be restored.");
}

Prevention

Self-check bin\nfdriver.sys at startup and warn before the user picks Redirector mode.
Add the Netch directory to antivirus exclusions so nfdriver.sys isn't removed.
Re-extract the full release when restoring files.
Don't run disk 'cleaners' that remove .sys files from app folders.

When it happens

Trigger: Fresh install where the bin folder wasn't fully extracted; antivirus quarantined nfdriver.sys; the file was deleted by a 'cleaner' tool; building from source without the driver asset.

Common situations: Windows Defender flagging and removing nfdriver.sys; user ran a disk cleanup that removed 'unused' sys files; partial upgrade left an incomplete bin directory.

Related errors

AI-assisted analysis of netchx/netch@9d99eb1c5a (2026-08-13). Data as JSON: /api/errors/8826702ad0277853. Report an issue: GitHub.