babalae/better-genshin-impact · error · InvalidOperationException

只有根实例可以接受客户端连接登记。

Error message

只有根实例可以接受客户端连接登记。

What it means

Thrown by HandleConnectionOpenAsync when the current instance's type is not Primary. Only the root (Primary) instance is authorized to accept client connection registrations — it owns the registration state (_state.BetterGiConnectionsBySession, _state.WebViewConnectionsByProcessId). A ChildSession or WebView receiving a connection.open request indicates the IPC topology is inverted or a peer connected to the wrong pipe.

Source

Thrown at BetterGenshinImpact/Service/Instance/MessageHandlers/InstanceRequestHandler.cs:141

            ?? throw new ArgumentException("激活请求缺少命令行参数。");
        _enqueueActivation(activation.Arguments);
        return CacheActivationResponse(
            request.RequestId,
            InstanceIpcEnvelope.Response(request));
    }

    /// <summary>
    /// 校验子实例身份和启动记录后，将当前连接登记为有效子连接。
    /// v2 不再校验父实例 ID 或启动记录，而是使用根管道客户端的真实 PID 和 Session。
    /// </summary>
    private async Task<InstanceIpcEnvelope> HandleConnectionOpenAsync(
        InstanceConnection connection,
        InstanceIpcEnvelope request,
        CancellationToken cancellationToken)
    {
        if (_context.InstanceType != BetterGiInstanceType.Primary)
        {
            throw new InvalidOperationException("只有根实例可以接受客户端连接登记。");
        }
        if (connection.RemoteEndpoint is not null)
        {
            throw new InvalidOperationException("当前管道连接已经完成登记。");
        }
        if (connection.ClientProcessId is not { } processId
            || connection.ClientSessionId is not { } sessionId)
        {
            throw new InvalidOperationException("无法取得命名管道客户端的进程或 Session 信息。");
        }

        var open =
            request.Data?.ToObject<ConnectionOpenRequest>(InstanceIpcProtocol.Serializer)
            ?? throw new ArgumentException("连接登记请求缺少数据。");
        if (open.RequestedType == BetterGiInstanceType.WebView)
        {
            var endpoint = CreateEndpoint(
                BetterGiInstanceType.WebView,

View on GitHub (pinned to a7cb36712d)

Solutions

1. Verify InstancePipeNames.ForCurrentUser() produces consistent names across all processes — it derives from WindowsIdentity SID, so ensure no impersonation or SID resolution differences.
2. Ensure only the Primary process creates a NamedPipeServerStream with FirstPipeInstance — check InstanceBootstrap.Initialize logic.
3. Catch this error on the child side and log the pipe name and remote process to diagnose the misconnection.
4. If running tests, ensure InstanceContext.InstanceType is set correctly for each test process.

// Only the Primary instance should handle connection.open
// This is enforced inside HandleConnectionOpenAsync;
// callers should ensure this handler is only registered on Primary.

// Check if this instance is authorized to accept connections
static bool CanAcceptConnections(InstanceContext context)
    => context.InstanceType == BetterGiInstanceType.Primary;

When it happens

Trigger: A non-Primary instance receives an InstanceOperations.ConnectionOpen request. This should never happen in normal operation because clients connect to the root pipe (BetterGI.v2.user-<SID>.root) which is only owned by the Primary. It could occur if two processes both believe they are clients but one somehow acts as a server, or if pipe name resolution is wrong and a client connects to a child's pipe instead of the root's.

Common situations: A pipe name collision or misconfiguration where a child process's pipe has the same name as the root's; a version mismatch in pipe naming logic (InstancePipeNames); a malicious or buggy peer connecting to the wrong endpoint; a test environment where InstanceContext was set up incorrectly.

Related errors

• 根实例分配了不匹配的客户端类型：{openResponse.AssignedType}。
• 只有根实例可以向 BetterGI 客户端分发激活消息。
• 根实例连接响应缺少数据。
• 当前管道连接已经完成登记。
• 当前JS脚本不允许使用HTTP请求，请在调度器通用设置中启用“JS HTTP权限”

AI-assisted analysis of babalae/better-genshin-impact@a7cb36712d (2026-08-13). Data as JSON: /api/errors/1db09bbc310dbbdf. Report an issue: GitHub.