What causes "{Name} 控制器启动失败" in netchx/netch?

Read the log file that OnStartFailed just opened (logging\ .log) for the child's actual error line.

netchx/netch · error · MessageException

{Name} 控制器启动失败

Error message

{Name} 控制器启动失败

What it means

Thrown by Guard.StartGuardAsync when the launched child process transitioned to State.Stopped during startup — meaning ReadOutputAsync saw a line matching one of the controller's FailedKeywords, or the process exited before printing any StartedKeyword. The controller had RedirectOutput on and a non-empty StartedKeywords list, so it actively watched stdout/stderr. OnStartFailed runs first (default opens the log file), then this exception propagates.

Source

Thrown at Netch/Controllers/Guard.cs:96

            {
                // Skip, No started keyword
                State = State.Started;
                return;
            }

            // wait ReadOutput change State
            for (var i = 0; i < 1000; i++)
            {
                await Task.Delay(50);
                switch (State)
                {
                    case State.Started:
                        OnStarted();
                        return;
                    case State.Stopped:
                        await StopGuardAsync();
                        OnStartFailed();
                        throw new MessageException($"{Name} 控制器启动失败");
                }
            }

            await StopGuardAsync();
            throw new MessageException($"{Name} 控制器启动超时");
        }
    }

    private async Task ReadOutputAsync(TextReader reader)
    {
        string? line;
        while ((line = await reader.ReadLineAsync()) != null)
        {
            await _logStreamWriter!.WriteLineAsync(line);
            OnReadNewLine(line);

            if (State == State.Starting)
            {

View on GitHub (pinned to 9d99eb1c5a)

Solutions

Read the log file that OnStartFailed just opened (logging\<Name>.log) for the child's actual error line.
Correct the server/mode configuration that was serialized into the child's arguments.
Free the port the child needs or stop the conflicting process.
If the child needs a runtime (e.g. Npcap for pcap2socks), install it.
Reinstall Netch to get a binary version whose CLI matches the controller's arg assembly.

Defensive patterns

Strategy: try-catch

Try / catch

try { await guard.StartGuardAsync(args); }
catch (MessageException ex) when (ex.Message.EndsWith("控制器启动失败"))
{
    // OnStartFailed already opened logging\<Name>.log; surface its last line to the user.
    var lastLine = File.ReadLines(guard.LogPath).LastOrDefault();
    Global.MainForm.StatusText($"{guard.Name} failed: {lastLine}");
}

Prevention

Always read the child's log file on failure rather than guessing from the generic message.
Keep StartedKeywords/FailedKeywords in sync with the bundled binary version.
Free the child's required ports before launching to avoid early exit.
Install the child's runtime dependencies (Npcap, etc.) before first launch.

When it happens

Trigger: Child process (pcap2socks, v2ray, etc.) prints a configured FailedKeyword and exits; child crashes immediately due to bad arguments assembled by the controller; child cannot bind its listen port; child missing its own runtime dependency so it errors out and dies.

Common situations: Server config (host/port/password) passed as args is rejected by the child; port conflict for the child's own listener; version mismatch between Netch's arg format and the bundled binary; certificate/permission errors in the child logged as a failure keyword.

Related errors

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