What causes "Unhandled Exception {e.Message}" in netchx/netch?

Open the log file that was just launched (Constants.LogFile) and read the full stack trace of the 'Unhandled Exception When Start MainController' entry.

netchx/netch · error · MessageException

Unhandled Exception {e.Message}

Error message

Unhandled Exception
{e.Message}

What it means

Catch-all in MainController.StartAsync for any exception during startup that is not MessageException, DllNotFoundException, or FileNotFoundException. It logs the full exception to Serilog, opens Constants.LogFile for the user, and rethrows a MessageException with a generic 'Unhandled Exception' wrapper plus the original message. The original stack trace is in the log, not in the surfaced message.

Source

Thrown at Netch/Controllers/MainController.cs:90

            await ModeController.StartAsync(Socks5Server, mode);
        }
        catch (Exception e)
        {
            releaser.Dispose();
            await StopAsync();

            switch (e)
            {
                case DllNotFoundException:
                case FileNotFoundException:
                    throw new Exception(e.Message + "\n\n" + i18N.Translate("Missing File or runtime components"));
                case MessageException:
                    throw;
                default:
                    Log.Error(e, "Unhandled Exception When Start MainController");
                    Utils.Utils.Open(Constants.LogFile);
                    throw new MessageException($"{i18N.Translate("Unhandled Exception")}\n{e.Message}");
            }
        }
    }

    public static async Task StopAsync()
    {
        if (Lock.CurrentCount == 0)
        {
            (await Lock.EnterAsync()).Dispose();
            if (ServerController == null && ModeController == null)
                // stopped
                return;

            // else begin stop
        }

        using var _ = await Lock.EnterAsync();

View on GitHub (pinned to 9d99eb1c5a)

Solutions

Open the log file that was just launched (Constants.LogFile) and read the full stack trace of the 'Unhandled Exception When Start MainController' entry.
If the cause is UnauthorizedAccess/Win32, relaunch Netch as administrator.
Address the specific inner exception type from the log.
If it looks like a bug, report it with the log attached.

Defensive patterns

Strategy: try-catch

Try / catch

try { await MainController.StartAsync(server, mode); }
catch (MessageException ex) when (ex.Message.StartsWith("Unhandled Exception"))
{
    // The full stack trace was already written to Constants.LogFile and opened.
    // Read the latest 'Unhandled Exception When Start MainController' entry for triage.
    Log.Information("Surfaced unhandled start failure; see {LogFile}", Constants.LogFile);
}

Prevention

Run Netch as administrator so Win32/route/firewall APIs don't throw UnauthorizedAccess.
Always attach the log file (which the controller opens for you) when reporting.
Don't Start while a Stop is in flight — let the async lock settle.
Keep server/mode objects non-null and validated before Start.

When it happens

Trigger: NullReferenceException, InvalidOperationException, UnauthorizedAccessException (no admin), network/socket exceptions, or any bug inside a controller's StartAsync that wasn't already a MessageException.

Common situations: Netch not run as administrator when a controller needs elevation; a code regression throwing on a null server/mode field; firewall/rule APIs throwing Win32 errors; race between Start and Stop mutating controller fields.

Related errors

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